Tworzenie aplikacji internetowej przy użyciu protokołu OAuth 2.0 usługi Azure DevOps
Azure DevOps Services
Ważne
Te informacje są przeznaczone tylko dla istniejących aplikacji OAuth usługi Azure DevOps. Nowi deweloperzy aplikacji powinni używać protokołu OAuth identyfikatora Entra firmy Microsoft do integracji z usługą Azure DevOps.
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
Przejdź do witryny ,
https://app.vsaex.visualstudio.com/app/registeraby zarejestrować aplikację.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.
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.
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
- 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. |
- 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=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
&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
codezapytania 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 }
}
Ważne
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 }
}
Ważne
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 5 lat wpis tajny aplikacji wygaśnie. Oczekuje się, że ponownie wygenerujesz wpis tajny aplikacji, aby nadal móc tworzyć tokeny dostępu i używać tokenów dostępu oraz tokenów odświeżania. Aby to zrobić, możesz kliknąć przycisk "Wygeneruj ponownie wpis tajny", który wyświetli okno dialogowe, aby potwierdzić, że chcesz ukończyć tę akcję.
Po potwierdzeniu, że chcesz ponownie wygenerować, poprzedni wpis tajny aplikacji nie będzie już 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.
Często zadawane pytania (FAQ)
Pyt.: 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.
Pyt.: 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.
Pyt.: 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.
Pyt.: 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.
Pyt.: 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 dostęp do aplikacji innej firmy za pośrednictwem protokołu OAuth nie został wyłączony przez administratora organizacji 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.
Pyt.: Czy mogę używać protokołu OAuth z punktami końcowymi protokołu SOAP i interfejsami API REST?
Odpowiedź: Nie. Protokół OAuth jest obecnie obsługiwany tylko w interfejsach API REST.
Pyt.: Jak uzyskać szczegóły załączników dla mojego elementu roboczego przy użyciu interfejsów API REST usługi Azure DevOps?
1: Najpierw pobierz szczegóły elementu roboczego za pomocą elementu roboczego — pobierz interfejs API REST elementu roboczego :
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Aby uzyskać szczegóły załączników, należy dodać następujący parametr do adresu URL:
$expand=all
Dzięki wynikom uzyskasz właściwość relations. Możesz tam znaleźć adres URL załączników i w adresie URL, który można znaleźć. Na przykład:
$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0
$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json
$split = ($workitem.relations.url).Split('/')
$attachmentId = $split[$split.count - 1]
# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs
Powiązane artykuły
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla