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

Azure DevOps Services

Importante

Azure DevOps OAuth sera abandonné 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 d’avril 2025, nous arrêtons 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.

Commencer avec Azure DevOps OAuth

1. Inscrire votre application

1. Accédez à https://app.vsaex.visualstudio.com/app/register pour enregistrer 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.

   

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

     

   • 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	Catégorie	Remarques
client_id	Identifiant Unique Global (GUID)	ID affecté à votre application lors de son inscription.
type_de_réponse	chaîne	Assertion
état	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.
portée	chaîne	É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.

2. 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 de page	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 de remplacement dans le contenu de l'exemple de requête précédent :

• {0}: Clé secrète client codée en URL acquise lors de l’enregistrement de l’application
• {1} : URL encodée « code » fournie via le paramètre de requête code vers l’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 de page	Valeur
Type de contenu	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 de remplacement dans le contenu de l'exemple de requête précédent :

• {0}: Clé secrète client codée en URL acquise lors de l’enregistrement de l’application
• {1}: jeton d’actualisation encodé sous forme 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 un secret client

Les secrets d’application expirent régulièrement tous les 60 jours (à compter de mars 2025). Vous pouvez avoir deux secrets à tout moment. Continuez à créer et à utiliser des jetons d’accès et des jetons d’actualisation en faisant pivoter votre secret d’application bientôt à expiration avec un nouveau secret d’application. Cette opération peut être effectuée sur la page d’inscription de l’application sur le profil Visual Studio ou via les API du secret d’inscription. Pour utiliser les API, vous devez utiliser un jeton d’accès Entra avec l’étenduevso.tokens.

1. Créez un secret secondaire en sélectionnant « Générer un secret » pour « Secret 2 ». (Utilisez l’API Créer un secret d’inscription.)

2. Ensuite, confirmez dans la fenêtre modale que vous souhaitez effectuer cette action.

3. Mettez à jour votre application pour utiliser le nouveau secret #2 avant l’expiration du secret #1. En gérant deux secrets à la fois, il n’existe aucun temps d’arrêt pour vos utilisateurs en raison de l’expiration des secrets.

4. Secret #1 expire naturellement et tous les jetons précédents cessent de fonctionner.

5. Quand il est temps de changer un Secret #2 proche de l'expiration, vous pouvez répéter ce processus en régénérant le Secret #1 et en utilisant le Secret #1 régénéré à la place du Secret #2. (Utilisez l’API de rotation du secret d’inscription.)

Si des secrets sont divulguées, vous pouvez rapidement révoquer le secret en cliquant sur « Régénérer le secret ». Une fois que vous avez confirmé 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. Utilisez la méthode de rotation de double secret pour réduire le temps d’arrêt tout en révoquant le secret divulgué grâce à la régénération.

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 fenêtre modale s’affiche pour confirmer la suppression.

   

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.

Articles connexes

• Choix de la méthode d’authentification appropriée
• Utiliser Microsoft Entra ID OAuth
• Autorisations et accès par défaut pour Azure DevOps
• Gérer les autorisations