Använda Azure DevOps OAuth 2.0 för att skapa en webbapp
Azure DevOps Services
Viktigt!
Azure DevOps OAuth är planerat för utfasning 2026. Den här informationen gäller endast för befintliga Azure DevOps OAuth-appar. Om du vill skapa nya appar använder du Microsoft Entra ID OAuth för att integrera med Azure DevOps. Från och med februari 2025 kommer vi att sluta acceptera nya Azure DevOps OAuth-appar. Läs mer i vårt blogginlägg.
Azure DevOps är en identitetsprovider för OAuth 2.0-appar. Vår implementering av OAuth 2.0 gör att utvecklare kan auktorisera sin app för användare och få åtkomsttoken för Azure DevOps-resurser.
Kom igång med Azure DevOps OAuth
1. Registrera din app
Viktigt!
Skapandet av nya appar kommer att blockeras från och med februari 2025.
Gå till för att
https://app.vsaex.visualstudio.com/app/registerregistrera din app.Välj de omfång som programmet behöver och använd sedan samma omfång när du auktoriserar din app. Om du har registrerat din app med förhandsversions-API:erna registrerar du igen eftersom de omfång som du använde nu är inaktuella.
Välj Skapa program.
Sidan programinställningar visas.
När Azure DevOps Services visar auktoriseringsgodkännandesidan för din användare använder den företagets namn, appnamn och beskrivningar. Den använder också URL:er för företagets webbplats, appwebbplats och användarvillkor och sekretesspolicyer.
När Azure DevOps Services ber om en användares auktorisering och användaren beviljar det omdirigeras användarens webbläsare till din auktoriseringswebbadress med auktoriseringskoden. Återanrops-URL:en måste vara en säker anslutning (https) för att överföra koden tillbaka till appen och exakt matcha url:en som registrerats i din app. Om den inte gör det visas en 400-felsida i stället för en sida där användaren uppmanas att bevilja auktorisering till din app.
Anropa auktoriserings-URL:en och skicka ditt app-ID och auktoriserade omfång när du vill att en användare ska tillåta din app att komma åt organisationen. Anropa URL:en för åtkomsttoken när du vill hämta en åtkomsttoken för att anropa ett REST-API för Azure DevOps Services.
Inställningarna för varje app som du registrerar är tillgängliga från din profil https://app.vssps.visualstudio.com/profile/view.
2. Auktorisera din app
- Om användaren inte gav appen åtkomst till organisationen anropar du auktoriserings-URL:en. Den anropar dig med en auktoriseringskod om användaren godkänner auktoriseringen.
https://app.vssps.visualstudio.com/oauth2/authorize
?client_id={app ID}
&response_type={Assertion}
&state={state}
&scope={scope}
&redirect_uri={callback URL}
| Parameter | Type | Anteckningar |
|---|---|---|
| client_id | GUID | Det ID som tilldelades din app när den registrerades. |
| response_type | sträng | Assertion |
| tillstånd | string | Kan vara valfritt värde. Vanligtvis ett genererat strängvärde som korrelerar återanropet med dess associerade auktoriseringsbegäran. |
| omfattning | sträng | Omfång som registrerats med appen. Blanksteg har separerats. Se tillgängliga omfång. |
| redirect_uri | webbadress | Återanrops-URL för din app. Måste exakt matcha url:en som registrerats med appen. |
- Lägg till en länk eller knapp på webbplatsen som tar användaren till Azure DevOps Services-auktoriseringsslutpunkten:
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
Azure DevOps Services ber användaren att auktorisera din app.
Förutsatt att användaren godkänner omdirigerar Azure DevOps Services användarens webbläsare till din motringnings-URL, inklusive en kortlivad auktoriseringskod och det tillståndsvärde som anges i auktoriserings-URL:en:
https://fabrikam.azurewebsites.net/myapp/oauth-callback
?code={authorization code}
&state=User1
3. Hämta en åtkomst- och uppdateringstoken för användaren
Använd auktoriseringskoden för att begära en åtkomsttoken (och uppdateringstoken) för användaren. Tjänsten måste göra en HTTP-begäran från tjänst till tjänst till Azure DevOps Services.
URL – auktorisera app
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP-begärandehuvuden – auktorisera appen
| Header | Värde |
|---|---|
| Innehållstyp | application/x-www-form-urlencoded |
Content-Type: application/x-www-form-urlencoded
HTTP-begärandetext – auktorisera appen
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}
Ersätt platshållarvärdena i föregående exempelförfrågningstext:
- {0}: URL-kodad klienthemlighet som hämtades när appen registrerades
- {1}: URL-kodad "kod" som tillhandahålls via
codefrågeparametern till motringnings-URL:en - {2}: motringnings-URL som registrerats med appen
C#-exempel för att bilda begärandetexten – auktorisera appen
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
);
}
Svar – auktorisera app
{
"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 }
}
Kommentar
Spara refresh_token på ett säkert sätt så att appen inte behöver uppmana användaren att auktorisera igen. Åtkomsttoken upphör att gälla snabbt och bör inte sparas.
4. Använd åtkomsttoken
Om du vill använda en åtkomsttoken tar du med den som en ägartoken i auktoriseringshuvudet för din HTTP-begäran:
Authorization: Bearer {access_token}
Till exempel HTTP-begäran om att få de senaste versionerna för ett projekt:
GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}
5. Uppdatera en utgången åtkomsttoken
Om en användares åtkomsttoken upphör att gälla kan du använda uppdateringstoken som de hämtade i auktoriseringsflödet för att hämta en ny åtkomsttoken. Det är som den ursprungliga processen för att utbyta auktoriseringskoden mot en åtkomst- och uppdateringstoken.
URL – uppdateringstoken
POST https://app.vssps.visualstudio.com/oauth2/token
HTTP-begärandehuvuden – uppdateringstoken
| Header | Värde |
|---|---|
| Innehållstyp | application/x-www-form-urlencoded |
| Innehållslängd | Beräknad stränglängd för begärandetexten (se följande exempel) |
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654
HTTP-begärandetext – uppdateringstoken
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}
Ersätt platshållarvärdena i föregående exempelförfrågningstext:
- {0}: URL-kodad klienthemlighet som hämtades när appen registrerades
- {1}: URL-kodad uppdateringstoken för användaren
- {2}: motringnings-URL som registrerats med appen
Svar – uppdateringstoken
{
"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 }
}
Kommentar
En ny uppdateringstoken utfärdas för användaren. Spara den här nya token och använd den nästa gång du behöver hämta en ny åtkomsttoken för användaren.
Exempel
Du hittar ett C#-exempel som implementerar OAuth för att anropa REST API:er för Azure DevOps Services i vårt C# OAuth GitHub-exempel.
Återskapa klienthemlighet
Vart femte år upphör din programhemlighet att gälla. Återskapa din apphemlighet för att fortsätta att skapa och använda åtkomsttoken och uppdateringstoken. Om du vill göra det väljer du "Återskapa hemlighet", som sedan bekräftar att du vill slutföra den här åtgärden.
När du bekräftar att du vill återskapa fungerar inte längre den tidigare apphemligheten och alla tidigare token som har präglats med den här hemligheten slutar också att fungera. Se till att tidsanpassa den här klienthemlighetsrotationen väl för att minimera eventuella kundavbrott.
Ta bort din app
Om du inte längre behöver din app tar du bort den från din profil.
Gå till din profil på:
https://app.vssps.visualstudio.com/profile/view.Se till att du är på rätt klientorganisationssida genom att välja från den nedrullningsbara menyn under ditt namn i sidofältet.
Hitta appen under rubriken Program och tjänster i det vänstra sidofältet.
välj "Ta bort" på programregistreringssidan. En modal verkar bekräfta borttagningen.
När du har tagit bort appregistreringen bryts appen och vi slutar att mintera nya token eller acceptera mintade token för den här appen.
Vanliga frågor (FAQ)
F: Kan jag använda OAuth med min mobilapp?
S: Nej. Azure DevOps Services stöder endast webbserverflödet, så det finns inget sätt att implementera OAuth eftersom du inte kan lagra apphemligheten på ett säkert sätt.
F: Vilka fel eller särskilda villkor behöver jag hantera i min kod?
S: Kontrollera att du hanterar följande villkor:
- Om användaren nekar din appåtkomst returneras ingen auktoriseringskod. Använd inte auktoriseringskoden utan att söka efter avslag.
- Om användaren återkallar appens auktorisering är åtkomsttoken inte längre giltig. När din app använder token för att komma åt data returneras ett 401-fel. Begär auktorisering igen.
F: Jag vill felsöka min webbapp lokalt. Kan jag använda localhost för återanrops-URL:en när jag registrerar min app?
S: Ja. Azure DevOps Services tillåter nu localhost i din motringnings-URL. Se till att du använder https://localhost som början av din motringnings-URL när du registrerar din app.
F: Jag får ett HTTP 400-fel när jag försöker hämta en åtkomsttoken. Vad kan vara fel?
S: Kontrollera att du anger innehållstypen till application/x-www-form-urlencoded i begärandehuvudet.
F: Jag får ett HTTP 401-fel när jag använder en OAuth-baserad åtkomsttoken, men en PAT med samma omfång fungerar bra. Varför?
S: Kontrollera att organisationens administratör inte inaktiverade programåtkomst från tredje part via OAuth på https://dev.azure.com/{your-org-name}/_settings/organizationPolicy.
I det här scenariot fungerar flödet för att auktorisera en app och generera en åtkomsttoken, men alla REST-API:er returnerar endast ett fel, till exempel TF400813: The user "<GUID>" is not authorized to access this resource.