Udostępnij za pośrednictwem

Tworzenie aplikacji internetowej przy użyciu protokołu OAuth 2.0 usługi Azure DevOps

  • Artykuł

Azure DevOps Services

Ważne

W 2026 r. usługa Azure DevOps OAuth ma zostać wycofana. Te informacje są przeznaczone tylko dla istniejących aplikacji OAuth usługi Azure DevOps. Aby utworzyć nowe aplikacje, użyj protokołu OAuth identyfikatora Entra firmy Microsoft do integracji z usługą Azure DevOps. Od lutego 2025 r. przestaniemy akceptować nowe aplikacje OAuth usługi Azure DevOps. Dowiedz się więcej w naszym wpisie w blogu.

Azure DevOps to dostawca tożsamości dla aplikacji OAuth 2.0. Nasza implementacja protokołu OAuth 2.0 umożliwia deweloperom autoryzowanie aplikacji dla użytkowników i uzyskiwanie tokenów dostępu dla zasobów usługi Azure DevOps.

Rozpoczynanie pracy z usługą Azure DevOps OAuth

1. Rejestrowanie aplikacji

Ważne

Tworzenie nowej aplikacji zostanie zablokowane od lutego 2025 r.

  1. Przejdź do witryny , https://app.vsaex.visualstudio.com/app/register aby zarejestrować aplikację.

  2. Wybierz zakresy wymagane przez aplikację, a następnie użyj tych samych zakresów podczas autoryzowania aplikacji. Jeśli zarejestrowano aplikację przy użyciu interfejsów API w wersji zapoznawczej, zarejestruj się ponownie, ponieważ używane zakresy są teraz przestarzałe.

  3. Wybierz pozycję Utwórz aplikację.

    Zostanie wyświetlona strona ustawień aplikacji.

    Zrzut ekranu przedstawiający ustawienia aplikacji dla aplikacji.

    • Gdy usługa Azure DevOps Services wyświetla użytkownikowi stronę zatwierdzania autoryzacji, używa nazwy firmy, nazwy aplikacji i opisów. Używa również adresów URL firmowej witryny internetowej, witryny internetowej aplikacji oraz warunków korzystania z usług i zasad zachowania poufności informacji.

      Zrzut ekranu przedstawiający stronę autoryzacji usługi Visual Studio Codespaces z informacjami o firmie i aplikacji.

    • Gdy usługa Azure DevOps Services prosi o autoryzację użytkownika, a użytkownik udziela jej, przeglądarka użytkownika zostanie przekierowana do adresu URL wywołania zwrotnego autoryzacji z kodem autoryzacji. Adres URL wywołania zwrotnego musi być bezpiecznym połączeniem (https), aby przenieść kod z powrotem do aplikacji i dokładnie odpowiadać adresowi URL zarejestrowanemu w aplikacji. Jeśli tak nie jest, zostanie wyświetlona strona błędu 400 zamiast strony z prośbą użytkownika o udzielenie autoryzacji aplikacji.

  4. Wywołaj adres URL autoryzacji i przekaż identyfikator aplikacji i autoryzowane zakresy, jeśli chcesz, aby użytkownik autoryzował aplikację w celu uzyskania dostępu do organizacji. Wywołaj adres URL tokenu dostępu, jeśli chcesz uzyskać token dostępu w celu wywołania interfejsu API REST usługi Azure DevOps Services.

Ustawienia dla każdej zarejestrowanej aplikacji są dostępne w profilu https://app.vssps.visualstudio.com/profile/view.

2. Autoryzowanie aplikacji

  1. Jeśli użytkownik nie autoryzuje aplikacji dostępu do swojej organizacji, wywołaj adres URL autoryzacji. Wywołuje cię z powrotem przy użyciu kodu autoryzacji, jeśli użytkownik zatwierdzi autoryzację.
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}
Parametr Type Uwagi
client_id Identyfikator GUID Identyfikator przypisany do aplikacji, gdy został zarejestrowany.
response_type string Assertion
stan string Może być dowolną wartością. Zazwyczaj wygenerowana wartość ciągu, która koreluje wywołanie zwrotne ze skojarzonym żądaniem autoryzacji.
zakres string Zakresy zarejestrowane w aplikacji. Spacja oddzielona. Zobacz dostępne zakresy.
redirect_uri URL Adres URL wywołania zwrotnego dla aplikacji. Musi dokładnie odpowiadać adresowi URL zarejestrowanego w aplikacji.
  1. Dodaj link lub przycisk do witryny, który przenosi użytkownika do punktu końcowego autoryzacji usług Azure DevOps Services:
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Usługa Azure DevOps Services prosi użytkownika o autoryzowanie aplikacji.

Zakładając, że użytkownik akceptuje, usługa Azure DevOps Services przekierowuje przeglądarkę użytkownika do adresu URL wywołania zwrotnego, w tym krótkotrwały kod autoryzacji i wartość stanu podaną w adresie URL autoryzacji:

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3. Uzyskiwanie tokenu dostępu i odświeżania dla użytkownika

Użyj kodu autoryzacji, aby zażądać tokenu dostępu (i tokenu odświeżania) dla użytkownika. Twoja usługa musi wysłać żądanie HTTP typu service-to-service do usług Azure DevOps Services.

Adres URL — autoryzowanie aplikacji

POST https://app.vssps.visualstudio.com/oauth2/token

Nagłówki żądań HTTP — autoryzowanie aplikacji

Nagłówek Wartość
Typ zawartości application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded

Treść żądania HTTP — autoryzowanie aplikacji

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

Zastąp wartości symboli zastępczych w poprzedniej przykładowej treści żądania:

  • {0}: zakodowany w adresie URL klucz tajny klienta uzyskany podczas rejestrowania aplikacji
  • {1}: adres URL zakodowany "kod" podany za pośrednictwem parametru code zapytania do adresu URL wywołania zwrotnego
  • {2}: adres URL wywołania zwrotnego zarejestrowany w aplikacji

Przykład w języku C# do utworzenia treści żądania — autoryzowanie aplikacji

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

Odpowiedź — autoryzowanie aplikacji

{
    "access_token": { access token for the user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { refresh token to use to acquire a new access token }
}

Uwaga

Bezpiecznie utrwalić refresh_token , aby aplikacja nie musiała ponownie monitować użytkownika o autoryzację. Tokeny dostępu wygasają szybko i nie powinny być utrwalane.

4. Użyj tokenu dostępu

Aby użyć tokenu dostępu, dołącz go jako token elementu nośnego w nagłówku autoryzacji żądania HTTP:

Authorization: Bearer {access_token}

Na przykład żądanie HTTP w celu pobrania ostatnich kompilacji dla projektu:

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Odśwież wygasły token dostępu

Jeśli token dostępu użytkownika wygaśnie, możesz użyć tokenu odświeżania uzyskanego w przepływie autoryzacji, aby uzyskać nowy token dostępu. Jest to jak oryginalny proces wymiany kodu autoryzacji dla tokenu dostępu i odświeżania.

Adres URL — token odświeżania

POST https://app.vssps.visualstudio.com/oauth2/token

Nagłówki żądań HTTP — token odświeżania

Nagłówek Wartość
Typ zawartości application/x-www-form-urlencoded
Długość zawartości Obliczona długość ciągu treści żądania (zobacz poniższy przykład) 
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Treść żądania HTTP — token odświeżania

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Zastąp wartości symboli zastępczych w poprzedniej przykładowej treści żądania:

  • {0}: zakodowany w adresie URL klucz tajny klienta uzyskany podczas rejestrowania aplikacji
  • {1}: token odświeżania zakodowany w adresie URL dla użytkownika
  • {2}: adres URL wywołania zwrotnego zarejestrowany w aplikacji

Odpowiedź — token odświeżania

{
    "access_token": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

Uwaga

Dla użytkownika zostanie wystawiony nowy token odświeżania. Utrwalij ten nowy token i użyj go przy następnym uzyskaniu nowego tokenu dostępu dla użytkownika.

Przykłady

Przykład języka C#, który implementuje protokół OAuth w celu wywoływania interfejsów API REST usługi Azure DevOps Services, można znaleźć w naszym przykładzie usługi GitHub OAuth języka C#.

Ponowne generowanie wpisu tajnego klienta

Co pięć lat wpis tajny aplikacji wygasa. Wygeneruj ponownie wpis tajny aplikacji, aby nadal tworzyć tokeny dostępu i używać tokenów dostępu oraz tokenów odświeżania. W tym celu wybierz pozycję "Wygeneruj ponownie wpis tajny", co następnie potwierdza, że chcesz wykonać tę akcję.

Zrzut ekranu przedstawiający potwierdzanie ponownego odnawiania wpisu tajnego.

Po potwierdzeniu, że chcesz ponownie wygenerować, poprzedni wpis tajny aplikacji nie działa, a wszystkie poprzednie tokeny wybione z tym wpisem tajnym również przestaną działać. Pamiętaj, aby skrócić czas rotacji wpisu tajnego klienta, aby zminimalizować wszelkie przestoje klientów.

Usunięcie aplikacji

Jeśli aplikacja nie jest już potrzebna, usuń ją z profilu.

  1. Przejdź do swojego profilu pod adresem: https://app.vssps.visualstudio.com/profile/view.

  2. Upewnij się, że jesteś na właściwej stronie dzierżawy, wybierając z menu rozwijanego pod nazwą na pasku bocznym.

  3. Znajdź aplikację w nagłówku Aplikacje i usługi na lewym pasku bocznym.

  4. wybierz pozycję "Usuń" na stronie rejestracji aplikacji. Modalny wydaje się potwierdzać usunięcie.

    Zrzut ekranu przedstawiający stronę metadanych aplikacji z wyróżnionym przyciskiem usuwania

  5. Po usunięciu rejestracji aplikacji aplikacja zostanie przerwana i przestaniemy wybić nowe tokeny lub akceptujemy tokeny wybitne dla tej aplikacji.

Często zadawane pytania (FAQ)

.: Czy mogę używać protokołu OAuth z moją aplikacją na telefon komórkowy?

Odpowiedź: Nie. Usługa Azure DevOps Services obsługuje tylko przepływ serwera internetowego, więc nie ma możliwości zaimplementowania protokołu OAuth, ponieważ nie można bezpiecznie przechowywać wpisu tajnego aplikacji.

.: Jakie błędy lub specjalne warunki muszę obsłużyć w kodzie?

1: Upewnij się, że są obsługiwane następujące warunki:

  • Jeśli użytkownik odmówi dostępu do aplikacji, nie zostanie zwrócony żaden kod autoryzacji. Nie używaj kodu autoryzacji bez sprawdzania odmowy.
  • Jeśli użytkownik odwoła autoryzację aplikacji, token dostępu nie jest już prawidłowy. Gdy aplikacja używa tokenu do uzyskiwania dostępu do danych, zwraca błąd 401. Ponownie zażądaj autoryzacji.

.: Chcę debugować aplikację internetową lokalnie. Czy mogę użyć hosta lokalnego dla adresu URL wywołania zwrotnego podczas rejestrowania aplikacji?

Odpowiedź: Tak. Usługa Azure DevOps Services umożliwia teraz hostowanie lokalne w adresie URL wywołania zwrotnego. Upewnij się, że używasz https://localhost jako początku adresu URL wywołania zwrotnego podczas rejestrowania aplikacji.

.: Otrzymuję błąd HTTP 400 podczas próby uzyskania tokenu dostępu. Co może być nie tak?

1: Sprawdź, czy typ zawartości został ustawiony na wartość application/x-www-form-urlencoded w nagłówku żądania.

.: Otrzymuję błąd HTTP 401 podczas korzystania z tokenu dostępu opartego na protokole OAuth, ale pat z tym samym zakresem działa prawidłowo. Dlaczego?

Uwierzytelnianie: Sprawdź, czy administrator twojej organizacji nie wyłączył dostępu do aplikacji innej firmy za pośrednictwem protokołu OAuth pod adresem https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. W tym scenariuszu przepływ umożliwiający autoryzowanie aplikacji i generowanie tokenu dostępu działa, ale wszystkie interfejsy API REST zwracają tylko błąd, taki jak TF400813: The user "<GUID>" is not authorized to access this resource.