Använda Azure DevOps OAuth 2.0 för att skapa en webbapp
Azure DevOps Services
Viktigt!
Den här informationen gäller endast för befintliga Azure DevOps OAuth-appar. Nya apputvecklare bör använda Microsoft Entra ID OAuth för att integrera med Azure DevOps.
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
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=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 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
| Sidhuvud | 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 }
}
Viktigt!
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
| Sidhuvud | 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 }
}
Viktigt!
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 upphöra. Du förväntas återskapa din apphemlighet för att fortsätta att kunna skapa och använda åtkomsttoken och uppdateringstoken. För att göra det kan du klicka på knappen "Återskapa hemlighet", som visar en dialogruta för att bekräfta 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.
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 programåtkomst från tredje part via OAuth inte har inaktiverats av organisationens administratör 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.
F: Kan jag använda OAuth med SOAP-slutpunkter och REST-API:er?
S: Nej. OAuth stöds endast i REST-API:erna just nu.
F: Hur får jag information om bifogade filer för mitt arbetsobjekt med hjälp av Rest-API:er för Azure DevOps?
S: Hämta först arbetsobjektsinformationen med Arbetsobjekt – Hämta REST API för arbetsobjekt :
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
För att få information om bifogade filer måste du lägga till följande parameter i URL:en:
$expand=all
Med resultatet får du relationsegenskapen. Där hittar du url:en för bifogade filer och i URL:en hittar du ID:t. Till exempel:
$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
Relaterade artiklar
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för