Partager via

Utiliser Azure DevOps OAuth 2.0 pour créer une application web

  • Article

Azure DevOps Services

Important

Azure DevOps OAuth est prévu pour la dépréciation en 2026. Ces informations concernent uniquement les applications OAuth Azure DevOps existantes. Pour créer des applications, utilisez l’ID OAuth Microsoft Entra pour l’intégrer à Azure DevOps. À compter de février 2025, nous cesserons d’accepter de nouvelles applications OAuth Azure DevOps. En savoir plus dans notre billet de blog.

Azure DevOps est un fournisseur d’identité pour les applications OAuth 2.0. Notre implémentation d’OAuth 2.0 permet aux développeurs d’autoriser leur application pour les utilisateurs et d’obtenir des jetons d’accès pour les ressources Azure DevOps.

Prise en main d’Azure DevOps OAuth

1. Inscrire votre application

Important

La création d’une nouvelle application sera bloquée à compter de février 2025.

  1. Accédez à l’inscription de https://app.vsaex.visualstudio.com/app/register votre application.

  2. Sélectionnez les étendues dont votre application a besoin, puis utilisez les mêmes étendues lorsque vous autorisez votre application. Si vous avez inscrit votre application à l’aide des API en préversion, réinscrivez-la, car les étendues que vous avez utilisées sont désormais déconseillées.

  3. Cliquez sur Créer une application.

    La page des paramètres de l’application s’affiche.

    Capture d’écran montrant les paramètres des applications pour votre application.

    • Quand Azure DevOps Services présente la page d’approbation d’autorisation à votre utilisateur, elle utilise le nom de votre entreprise, le nom de l’application et les descriptions. Il utilise également les URL pour votre site web d’entreprise, le site web de l’application et les conditions d’utilisation et les déclarations de confidentialité.

      Capture d’écran montrant la page d’autorisation Visual Studio Codespaces avec les informations de votre entreprise et de votre application.

    • Quand Azure DevOps Services demande l’autorisation d’un utilisateur et que l’utilisateur l’accorde, le navigateur de l’utilisateur est redirigé vers votre URL de rappel d’autorisation avec le code d’autorisation. L’URL de rappel doit être une connexion sécurisée (https) pour transférer le code vers l’application et correspondre exactement à l’URL inscrite dans votre application. Si ce n’est pas le cas, une page d’erreur 400 s’affiche au lieu d’une page demandant à l’utilisateur d’accorder l’autorisation à votre application.

  4. Appelez l’URL d’autorisation et transmettez votre ID d’application et les étendues autorisées lorsque vous souhaitez qu’un utilisateur autorise votre application à accéder à son organisation. Appelez l’URL du jeton d’accès lorsque vous souhaitez obtenir un jeton d’accès pour appeler une API REST Azure DevOps Services.

Les paramètres de chaque application que vous inscrivez sont disponibles à partir de votre profil https://app.vssps.visualstudio.com/profile/view.

2. Autoriser votre application

  1. Si votre utilisateur n’a pas autorisé votre application à accéder à son organisation, appelez l’URL d’autorisation. Il vous rappelle avec un code d’autorisation, si l’utilisateur approuve l’autorisation.
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id={app ID}
        &response_type={Assertion}
        &state={state}
        &scope={scope}
        &redirect_uri={callback URL}
Paramètre Type Notes
client_id GUID ID affecté à votre application lors de son inscription.
response_type string Assertion
state chaîne Peut avoir n’importe quelle valeur. En règle générale, une valeur de chaîne générée qui met en corrélation le rappel avec sa demande d’autorisation associée.
scope string Étendues inscrites auprès de l’application. Espace séparé. Consultez les étendues disponibles.
redirect_uri URL URL de rappel de votre application. Doit correspondre exactement à l’URL inscrite auprès de l’application.
  1. Ajoutez un lien ou un bouton à votre site qui amène l’utilisateur au point de terminaison d’autorisation Azure DevOps Services :
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 demande à l’utilisateur d’autoriser votre application.

En supposant que l’utilisateur accepte, Azure DevOps Services redirige le navigateur de l’utilisateur vers votre URL de rappel, y compris un code d’autorisation de courte durée et la valeur d’état fournie dans l’URL d’autorisation :

https://fabrikam.azurewebsites.net/myapp/oauth-callback
        ?code={authorization code}
        &state=User1

3. Obtenir un jeton d’accès et d’actualisation pour l’utilisateur

Utilisez le code d’autorisation pour demander un jeton d’accès (et un jeton d’actualisation) pour l’utilisateur. Votre service doit effectuer une requête HTTP de service à service auprès d’Azure DevOps Services.

URL - Autoriser l’application

POST https://app.vssps.visualstudio.com/oauth2/token

En-têtes de requête HTTP - Autoriser l’application

En-tête Valeur
Type de contenu application/x-www-form-urlencoded 
Content-Type: application/x-www-form-urlencoded

Corps de la requête HTTP - Autoriser l’application

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}

Remplacez les valeurs d’espace réservé dans le corps de l’exemple de requête précédent :

  • {0}: Clé secrète client encodée d’URL acquise lors de l’inscription de l’application
  • {1}: URL encodée « code » fournie via le code paramètre de requête vers votre URL de rappel
  • {2}: URL de rappel inscrite auprès de l’application

Exemple C# pour former le corps de la demande - autoriser l’application

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
        );
}

Réponse - Autoriser l’application

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

Remarque

Conservez en toute sécurité le refresh_token afin que votre application n’ait pas besoin d’inviter l’utilisateur à autoriser à nouveau. Les jetons d’accès expirent rapidement et ne doivent pas être conservés.

4. Utiliser le jeton d’accès

Pour utiliser un jeton d’accès, incluez-le en tant que jeton de porteur dans l’en-tête d’autorisation de votre requête HTTP :

Authorization: Bearer {access_token}

Par exemple, la requête HTTP pour obtenir des builds récentes pour un projet :

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Actualiser un jeton d’accès expiré

Si le jeton d’accès d’un utilisateur expire, vous pouvez utiliser le jeton d’actualisation qu’il a acquis dans le flux d’autorisation pour obtenir un nouveau jeton d’accès. C’est comme le processus d’origine pour échanger le code d’autorisation pour un jeton d’accès et d’actualisation.

URL - Jeton d’actualisation

POST https://app.vssps.visualstudio.com/oauth2/token

En-têtes de requête HTTP - Jeton d’actualisation

En-tête Valeur
Content-Type application/x-www-form-urlencoded
Longueur du contenu Longueur de chaîne calculée du corps de la requête (voir l’exemple suivant) 
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Corps de la requête HTTP - Jeton d’actualisation

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Remplacez les valeurs d’espace réservé dans le corps de l’exemple de requête précédent :

  • {0}: Clé secrète client encodée d’URL acquise lors de l’inscription de l’application
  • {1}: jeton d’actualisation encodé d’URL pour l’utilisateur
  • {2}: URL de rappel inscrite auprès de l’application

Réponse - Jeton d’actualisation

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

Remarque

Un nouveau jeton d’actualisation est émis pour l’utilisateur. Conservez ce nouveau jeton et utilisez-le la prochaine fois que vous devez acquérir un nouveau jeton d’accès pour l’utilisateur.

Exemples

Vous trouverez un exemple C# qui implémente OAuth pour appeler des API REST Azure DevOps Services dans notre exemple GitHub OAuth C#.

Régénérer la clé secrète client

Tous les cinq ans, votre secret d’application expire. Régénérez votre secret d’application pour continuer à créer et utiliser des jetons d’accès et des jetons d’actualisation. Pour ce faire, sélectionnez « Régénérer le secret », qui confirme ensuite que vous souhaitez effectuer cette action.

Capture d’écran confirmant la régénération des secrets.

Lorsque vous confirmez que vous souhaitez régénérer, le secret d’application précédent ne fonctionne plus et tous les jetons précédents frappés avec ce secret arrêtent également de fonctionner. Veillez à ce que cette rotation des secrets client soit correctement planifiée pour réduire les temps d’arrêt des clients.

Supprimer votre application

Si vous n’avez plus besoin de votre application, supprimez-la de votre profil.

  1. Accédez à votre profil à l’adresse suivante : https://app.vssps.visualstudio.com/profile/view.

  2. Vérifiez que vous êtes sur la page du locataire correct en sélectionnant dans le menu déroulant sous votre nom dans la barre latérale.

  3. Recherchez l’application sous l’en-tête Applications et services dans la barre latérale gauche.

  4. sélectionnez « Supprimer » dans la page d’inscription de l’application. Une modale s’affiche pour confirmer votre suppression.

    Capture d’écran de la page de métadonnées de l’application avec le bouton Supprimer mis en surbrillance

  5. Une fois que vous avez supprimé l’inscription de l’application, l’application s’interrompt et nous arrêtons de frapper de nouveaux jetons ou d’accepter des jetons frappés pour cette application.

Forum Aux Questions (FAQ)

Q : Puis-je utiliser OAuth avec mon application de téléphone mobile ?

R : Non. Azure DevOps Services prend uniquement en charge le flux de serveur web. Il n’existe donc aucun moyen d’implémenter OAuth, car vous ne pouvez pas stocker en toute sécurité la clé secrète de l’application.

Q : Quelles erreurs ou conditions spéciales dois-je gérer dans mon code ?

R : Vérifiez que vous gérez les conditions suivantes :

  • Si votre utilisateur refuse l’accès à votre application, aucun code d’autorisation n’est retourné. N’utilisez pas le code d’autorisation sans vérifier le déni.
  • Si votre utilisateur révoque l’autorisation de votre application, le jeton d’accès n’est plus valide. Lorsque votre application utilise le jeton pour accéder aux données, une erreur 401 est retournée. Demandez à nouveau l’autorisation.

Q : Je souhaite déboguer mon application web localement. Puis-je utiliser localhost pour l’URL de rappel lorsque j’inscrit mon application ?

A : Oui. Azure DevOps Services autorise désormais localhost dans votre URL de rappel. Vérifiez que vous utilisez https://localhost comme début de votre URL de rappel lorsque vous inscrivez votre application.

Q : J’obtiens une erreur HTTP 400 lorsque j’essaie d’obtenir un jeton d’accès. Qu’est-ce qui pourrait se tromper ?

R : Vérifiez que vous définissez le type de contenu sur application/x-www-form-urlencoded dans votre en-tête de requête.

Q : J’obtiens une erreur HTTP 401 lorsque j’utilise un jeton d’accès OAuth, mais un pat avec la même étendue fonctionne correctement. Pourquoi ?

R : Vérifiez que l’administrateur de votre organisation n’a pas désactivé l’accès aux applications tierces via OAuth à l’adresse https://dev.azure.com/{your-org-name}/_settings/organizationPolicy. Dans ce scénario, le flux permettant d’autoriser une application et de générer un jeton d’accès fonctionne, mais toutes les API REST retournent uniquement une erreur, comme TF400813: The user "<GUID>" is not authorized to access this resource.