Azure DevOps OAuth 2.0 gebruiken om een web-app te maken
Azure DevOps Services
Belangrijk
Deze informatie is alleen bedoeld voor bestaande Azure DevOps OAuth-apps. Nieuwe app-ontwikkelaars moeten Microsoft Entra ID OAuth gebruiken om te integreren met Azure DevOps.
Azure DevOps is een id-provider voor OAuth 2.0-apps. Met onze implementatie van OAuth 2.0 kunnen ontwikkelaars hun app autoriseren voor gebruikers en toegangstokens krijgen voor Azure DevOps-resources.
Aan de slag met Azure DevOps OAuth
1. Uw app registreren
Ga naar
https://app.vsaex.visualstudio.com/app/registeruw app registreren.Selecteer de bereiken die uw toepassing nodig heeft en gebruik vervolgens dezelfde bereiken wanneer u uw app autoriseert. Als u uw app hebt geregistreerd met behulp van de preview-API's, registreert u zich opnieuw omdat de bereiken die u hebt gebruikt, nu worden afgeschaft.
Selecteer Toepassing maken.
De pagina met toepassingsinstellingen wordt weergegeven.
Wanneer Azure DevOps Services de autorisatiegoedkeuringspagina voor uw gebruiker presenteert, wordt uw bedrijfsnaam, app-naam en beschrijvingen gebruikt. Ook worden de URL's gebruikt voor uw bedrijfswebsite, app-website en servicevoorwaarden en privacyverklaringen.
Wanneer Azure DevOps Services vraagt om de autorisatie van een gebruiker en de gebruiker deze verleent, wordt de browser van de gebruiker omgeleid naar de callback-URL voor autorisatie met de autorisatiecode. De callback-URL moet een beveiligde verbinding (https) zijn om de code terug te zetten naar de app en exact overeen te komen met de URL die in uw app is geregistreerd. Als dit niet het probleem is, wordt er een 400-foutpagina weergegeven in plaats van een pagina waarin de gebruiker wordt gevraagd om toestemming te verlenen aan uw app.
Roep de autorisatie-URL aan en geef uw app-id en geautoriseerde bereiken door wanneer u een gebruiker uw app toestemming wilt geven voor toegang tot hun organisatie. Roep de URL van het toegangstoken aan wanneer u een toegangstoken wilt ophalen om een Azure DevOps Services REST API aan te roepen.
De instellingen voor elke app die u registreert, zijn beschikbaar via uw profiel https://app.vssps.visualstudio.com/profile/view.
2. Uw app autoriseren
- Als uw gebruiker uw app niet heeft geautoriseerd voor toegang tot hun organisatie, roept u de autorisatie-URL aan. U wordt terug met een autorisatiecode aanroepen als de gebruiker de autorisatie goedkeurt.
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id={app ID}
&response_type={Assertion}
&state={state}
&scope={scope}
&redirect_uri={callback URL}
| Parameter | Type | Opmerkingen |
|---|---|---|
| client_id | GUID | De id die is toegewezen aan uw app toen deze is geregistreerd. |
| response_type | tekenreeks | Assertion |
| staat | tekenreeks | Kan elke waarde zijn. Doorgaans een gegenereerde tekenreekswaarde die de callback correleert met de bijbehorende autorisatieaanvraag. |
| bereik | tekenreeks | Bereiken die zijn geregistreerd bij de app. Afstand gescheiden. Bekijk beschikbare bereiken. |
| redirect_uri | URL | Callback-URL voor uw app. Moet exact overeenkomen met de URL die is geregistreerd bij de app. |
- Voeg een koppeling of knop toe aan uw site waarmee de gebruiker naar het autorisatie-eindpunt van Azure DevOps Services wordt gebracht:
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
Azure DevOps Services vraagt de gebruiker om uw app te autoriseren.
Ervan uitgaande dat de gebruiker akkoord gaat, leidt Azure DevOps Services de browser van de gebruiker om naar uw callback-URL, inclusief een kortdurende autorisatiecode en de statuswaarde die is opgegeven in de autorisatie-URL:
https://fabrikam.azurewebsites.net/myapp/oauth-callback
?code={authorization code}
&state=User1
3. Een toegangs- en vernieuwingstoken voor de gebruiker ophalen
Gebruik de autorisatiecode om een toegangstoken (en vernieuwingstoken) aan te vragen voor de gebruiker. Uw service moet een HTTP-aanvraag voor de service naar Azure DevOps Services indienen.
URL : app autoriseren
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP-aanvraagheaders - app autoriseren
| Koptekst | Weergegeven als |
|---|---|
| Inhoudstype | application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded
Hoofdtekst van HTTP-aanvraag - app autoriseren
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}
Vervang de tijdelijke aanduidingen in de vorige voorbeeldaanvraagtekst:
- {0}: door URL gecodeerd clientgeheim dat is verkregen toen de app werd geregistreerd
- {1}: MET URL gecodeerde 'code' die via de
codequeryparameter is opgegeven voor uw callback-URL - {2}: callback-URL geregistreerd bij de app
C#-voorbeeld om de aanvraagbody te vormen - app autoriseren
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
);
}
Antwoord - app autoriseren
{
"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 }
}
Belangrijk
De refresh_token veilig behouden, zodat uw app de gebruiker niet opnieuw hoeft te vragen om toestemming te geven. Toegangstokens verlopen snel en mogen niet worden behouden.
4. Het toegangstoken gebruiken
Als u een toegangstoken wilt gebruiken, neemt u dit op als bearer-token in de autorisatie-header van uw HTTP-aanvraag:
Authorization: Bearer {access_token}
Bijvoorbeeld de HTTP-aanvraag voor het ophalen van recente builds voor een project:
GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}
5. Een verlopen toegangstoken vernieuwen
Als het toegangstoken van een gebruiker verloopt, kunt u het vernieuwingstoken gebruiken dat ze in de autorisatiestroom hebben verkregen om een nieuw toegangstoken op te halen. Het is vergelijkbaar met het oorspronkelijke proces voor het uitwisselen van de autorisatiecode voor een toegangs- en vernieuwingstoken.
URL : token vernieuwen
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP-aanvraagheaders - token vernieuwen
| Koptekst | Weergegeven als |
|---|---|
| Inhoudstype | application/x-www-form-urlencoded |
| Content-Length | Berekende tekenreekslengte van de aanvraagbody (zie het volgende voorbeeld) |
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654
Hoofdtekst van HTTP-aanvraag - token vernieuwen
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}
Vervang de tijdelijke aanduidingen in de vorige voorbeeldaanvraagtekst:
- {0}: door URL gecodeerd clientgeheim dat is verkregen toen de app werd geregistreerd
- {1}: met URL gecodeerd vernieuwingstoken voor de gebruiker
- {2}: callback-URL geregistreerd bij de app
Antwoord - token vernieuwen
{
"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 }
}
Belangrijk
Er wordt een nieuw vernieuwingstoken uitgegeven voor de gebruiker. Behoud dit nieuwe token en gebruik het de volgende keer dat u een nieuw toegangstoken voor de gebruiker moet verkrijgen.
Voorbeelden
U vindt een C#-voorbeeld waarmee OAuth wordt geïmplementeerd om AZURE DevOps Services REST API's aan te roepen in ons C# OAuth GitHub-voorbeeld.
Clientgeheim opnieuw genereren
Om de 5 jaar verloopt uw toepassingsgeheim. U verwacht dat u uw app-geheim opnieuw genereert, zodat u nog steeds toegangstokens en vernieuwingstokens kunt maken en gebruiken. Hiervoor klikt u op de knop Geheim opnieuw genereren. Er wordt een dialoogvenster weergegeven om te bevestigen dat u deze actie wilt voltooien.
Wanneer u bevestigt dat u opnieuw wilt genereren, werkt het vorige app-geheim niet meer en werken alle eerdere tokens die met dit geheim zijn gebruikt, ook niet meer. Zorg ervoor dat deze clientgeheimrotatie goed wordt getimed om downtime van klanten tot een minimum te beperken.
Veelgestelde vragen (FAQ's)
V: Kan ik OAuth gebruiken met mijn mobiele telefoon-app?
A: Nee. Azure DevOps Services ondersteunt alleen de webserverstroom, dus er is geen manier om OAuth te implementeren, omdat u het app-geheim niet veilig kunt opslaan.
V: Welke fouten of speciale voorwaarden moet ik afhandelen in mijn code?
A: Zorg ervoor dat u de volgende voorwaarden afhandelt:
- Als uw gebruiker de toegang tot uw app weigert, wordt er geen autorisatiecode geretourneerd. Gebruik de autorisatiecode niet zonder te controleren op weigering.
- Als uw gebruiker de autorisatie van uw app intrekt, is het toegangstoken niet meer geldig. Wanneer uw app het token gebruikt om toegang te krijgen tot gegevens, wordt er een 401-fout geretourneerd. Autorisatie opnieuw aanvragen.
V: Ik wil lokaal fouten opsporen in mijn web-app. Kan ik localhost gebruiken voor de callback-URL wanneer ik mijn app registreer?
A: Ja. Azure DevOps Services staat nu localhost toe in uw callback-URL. Zorg ervoor dat u https://localhost als het begin van uw callback-URL gebruikt wanneer u uw app registreert.
V: Ik krijg een HTTP 400-fout wanneer ik probeer een toegangstoken op te halen. Wat kan er mis zijn?
A: Controleer of u het inhoudstype instelt op application/x-www-form-urlencoded in de aanvraagheader.
V: Ik krijg een HTTP 401-fout wanneer ik een op OAuth gebaseerd toegangstoken gebruik, maar een PAT met hetzelfde bereik werkt prima. Waarom?
A: Controleer of de toegang van toepassingen van derden via OAuth niet is uitgeschakeld door de beheerder van uw organisatie op https://dev.azure.com/{your-org-name}/_settings/organizationPolicy.
In dit scenario werkt de stroom om een app te autoriseren en een toegangstoken te genereren, maar alle REST API's retourneren alleen een fout, zoals TF400813: The user "<GUID>" is not authorized to access this resource.
V: Kan ik OAuth gebruiken met de SOAP-eindpunten en REST API's?
A: Nee. OAuth wordt momenteel alleen ondersteund in de REST API's.
V: Hoe kan ik details van bijlagen voor mijn werkitem ophalen met behulp van Azure DevOps REST API's?
A: Haal eerst de details van het werkitem op met Werkitems - REST API voor werkitems ophalen:
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Als u de details van de bijlagen wilt ophalen, moet u de volgende parameter toevoegen aan de URL:
$expand=all
Met de resultaten krijgt u de relatie-eigenschap. Daar vindt u de URL van de bijlagen en binnen de URL kunt u de id vinden. Voorbeeld:
$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
Verwante artikelen:
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor