Använda Azure DevOps OAuth 2.0 för att skapa en webbapp

Azure DevOps-tjänster

Viktigt!

Azure DevOps OAuth kommer att avvecklas 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 april 2025 slutar vi att 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

1. Gå till https://app.vsaex.visualstudio.com/app/register för att registrera din app.

2. Välj de omfång som programmet behöver och använd sedan samma omfång när du auktoriserar din app. Om du registrerade din app med förhandsversions-API:erna, registrera den igen eftersom de omfång som du använde nu är inaktuella.

3. Välj Skapa program.

   Programinställningssidan 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.

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

1. Om användaren inte har auktoriserat din app för att få åtkomst till deras organisation, anropar du auktoriserings-URL:en. Den ringer tillbaka 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	Typ	Anteckningar
klient-id	GUID (globalt unikt identifierare)	Det ID som tilldelades din app när den registrerades.
svarstyp	sträng	Assertion
tillstånd	sträng	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. Mellanslag separerade. Se de tillgängliga omfången.
omdirigerings_uri	webbadress	Återanrops-URL för din app. Måste exakt matcha url:en som registrerats med appen.

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

Rubrik	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 code frågeparametern i din återuppringnings-URL
• {2}: tillbakakallnings-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 }
}

Anteckning

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

Rubrik	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}: tillbakakallnings-URL som registrerats med appen

Svar – förnyelsetoken

{
    "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 }
}

Anteckning

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

Programhemligheter upphör regelbundet att gälla var 60:e dag (från och med mars 2025). Du kan ha två hemligheter när som helst. Fortsätt att skapa och använda åtkomsttoken och uppdateringstoken genom att rotera din snart förfallna apphemlighet med en ny programhemlighet. Detta kan göras på appens registreringssida i Visual Studio-profilen eller via API:erna för registreringshemlighet. Om du vill använda API:erna måste du använda en Entra-åtkomsttoken med vso.tokens.

1. Skapa en sekundär hemlighet genom att välja "Generera hemlighet" för "Hemlig 2". (Använd API:et Skapa registreringshemlighet.)

2. Bekräfta sedan i modalen att du vill slutföra den här åtgärden.

3. Uppdatera din app så att den använder den nya hemligheten #2 innan hemlighet nr 1 upphör att gälla. Genom att hantera två hemligheter samtidigt finns det ingen stilleståndstid för dina användare på grund av att hemligheterna upphör att gälla.

4. Hemlighet nr 1 upphör naturligt och alla tidigare token upphör att fungera.

5. När det är dags att rotera en hemlighet som snart upphör att gälla #2 kan du upprepa den här processen genom att återskapa hemlighet nr 1 och använda den återskapade hemligheten #1 i stället för Hemlighet nr 2. (Använd API:et Rotera registreringshemlighet.)

Om hemligheter läcker kan du snabbt återkalla hemligheten genom att klicka på Återskapa hemlighet. När du har bekräftat 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. Använd metoden för rotation av dubbla hemligheter för att minimera drifttiden samtidigt som den läckta hemligheten annulleras genom regenerering.

Ta bort din app

Om du inte längre behöver din app tar du bort den från din profil.

1. Gå till din profil på: https://app.vssps.visualstudio.com/profile/view.

2. Se till att du är på rätt hyresgästsida genom att välja från rullgardinsmenyn under ditt namn i sidofältet.

3. Hitta appen under rubriken Program och tjänster i det vänstra sidofältet.

4. välj "Ta bort" på programregistreringssidan. En modal verkar bekräfta borttagningen.

   

5. När du har tagit bort appregistreringen slutar appen fungera, och vi slutar att prägla nya tokens eller acceptera präglade tokens 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.

Relaterade artiklar

• Välja rätt autentiseringsmetod
• Använda Microsoft Entra ID OAuth
• Standardbehörigheter och åtkomst i Azure DevOps
• Hantera auktoriseringar