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

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 marca 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 zarejestrowaliście swoją aplikację przy użyciu interfejsów API w wersji zapoznawczej, zarejestrujcie ją ponownie, ponieważ używane zakresy są teraz przestarzałe.

3. Wybierz pozycję Utwórz aplikację.

   Zostanie wyświetlona strona ustawień 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.

     

   • 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 udzielił pozwolenia aplikacji na dostęp 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	Typ	Uwagi
identyfikator klienta	Identyfikator GUID	Identyfikator przypisany do aplikacji, gdy został zarejestrowany.
typ_odpowiedzi	string	Assertion
stan	string	Może być dowolną wartością. Zazwyczaj jest to wygenerowana wartość ciągu znaków, która łączy wywołanie zwrotne ze skojarzonym żądaniem autoryzacji.
zakres	string	Zakresy zarejestrowane w aplikacji. Rozdzielone spacjami Zobacz dostępne zakresy.
adres_przekierowania	URL	Adres URL wywołania zwrotnego dla aplikacji. Musi dokładnie odpowiadać adresowi URL zarejestrowanego w aplikacji.

2. 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}: "kod" zakodowany w adresie URL, przekazany za pośrednictwem parametru zapytania code 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. Przypomina to oryginalny proces wymiany kodu autoryzacyjnego na token dostępu i token 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żający

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#.

Regeneracja sekretu klienta

Co pięć lat tajny klucz aplikacji wygasa. Wygeneruj ponownie tajny klucz aplikacji, aby nadal tworzyć i używać tokenów dostępu oraz tokenów odświeżania. W tym celu wybierz opcję "Wygeneruj ponownie sekret", aby potwierdzić wykonanie tej czynności.

Po potwierdzeniu, że chcesz ponownie wygenerować sekret, poprzedni sekret aplikacji przestaje działać, a wszystkie poprzednie tokeny wygenerowane tym sekretem również przestają działać. Upewnij się, że odpowiednio zaplanujesz rotację tajnego klucza klienta, aby zminimalizować wszelkie przestoje u 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żawcy, wybierając z menu rozwijanego pod Twoim imieniem 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. Pojawia się modalne okno, aby potwierdzić usunięcie.

   

5. Po usunięciu rejestracji aplikacji aplikacja przestaje działać, i przestajemy emitować nowe tokeny ani akceptować wyemitowane tokeny 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ć tajnego klucza aplikacji.

Jakie błędy lub specjalne warunki muszę rozwiązać w moim kodzie?

Upewnij się, że obsługujesz 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ć localhost dla adresu URL wywołania zwrotnego podczas rejestrowania aplikacji?

Odpowiedź: Tak. Usługa Azure DevOps Services teraz umożliwia użycie localhost w adresie URL wywołania zwrotnego. Pamiętaj, aby używać 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 w przypadku tokenu dostępu osobistego z tym samym zakresem wszystko działa prawidłowo. Dlaczego?

Sprawdź, czy administrator twojej organizacji nie wyłączył dostępu do aplikacji innej firmy za pośrednictwem protokołu OAuth w ustawieniach 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.

Powiązane artykuły

• Wybieranie właściwej metody uwierzytelniania
• Użyj Microsoft Entra ID OAuth
• Domyślne uprawnienia i dostęp dla usługi Azure DevOps
• Zarządzanie autoryzacjami