Delen via

Azure DevOps OAuth 2.0 gebruiken om een web-app te maken

  • Artikel

Azure DevOps Services

Belangrijk

Azure DevOps OAuth wordt in 2026 afgeschaft. Deze informatie is alleen bedoeld voor bestaande Azure DevOps OAuth-apps. Als u nieuwe apps wilt maken, gebruikt u OAuth van Microsoft Entra ID om te integreren met Azure DevOps. Vanaf februari 2025 accepteren we geen nieuwe Azure DevOps OAuth-apps meer. Meer informatie vindt u in ons blogbericht.

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

Belangrijk

Het maken van nieuwe apps wordt vanaf februari 2025 geblokkeerd.

  1. Ga naar https://app.vsaex.visualstudio.com/app/register uw app registreren.

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

  3. Selecteer Toepassing maken.

    De pagina met toepassingsinstellingen wordt weergegeven.

    Schermopname van de instellingen voor toepassingen voor uw app.

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

      Schermopname van de autorisatiepagina van Visual Studio Codespaces met uw bedrijfs- en app-gegevens.

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

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

  1. 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.
  1. 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=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 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 code queryparameter 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 }
}

Notitie

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
Lengte van inhoud 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 }
}

Notitie

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

Elke vijf jaar verloopt uw toepassingsgeheim. Genereer uw app-geheim opnieuw om toegangstokens te maken en te gebruiken en tokens te vernieuwen. Hiervoor selecteert u 'Geheim opnieuw genereren'. Vervolgens bevestigt u dat u deze actie wilt voltooien.

Schermopname van het bevestigen van de geheime regeneratie.

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.

De app verwijderen

Als u uw app niet meer nodig hebt, verwijdert u deze uit uw profiel.

  1. Ga naar uw profiel op: https://app.vssps.visualstudio.com/profile/view.

  2. Zorg ervoor dat u zich op de juiste tenantpagina bevindt door te selecteren in de vervolgkeuzelijst onder uw naam in de zijbalk.

  3. Zoek de app onder de header Toepassingen en services op de linkerzijbalk.

  4. selecteer 'Verwijderen' op de registratiepagina van de toepassing. Er wordt een modaal weergegeven om uw verwijdering te bevestigen.

    Schermopname van de pagina met app-metagegevens met de knop Verwijderen gemarkeerd

  5. Zodra u de app-registratie hebt verwijderd, wordt de app onderbroken en stoppen we met het munten van nieuwe tokens of het accepteren van munttokens voor deze app.

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 beheerder van uw organisatie de toegang van toepassingen van derden niet heeft uitgeschakeld via OAuth 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.