Utiliser Azure DevOps OAuth 2.0 pour créer une application web
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.
Accédez à l’inscription de
https://app.vsaex.visualstudio.com/app/register
votre application.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.
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.
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
- 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. |
- 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.
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.
Accédez à votre profil à l’adresse suivante :
https://app.vssps.visualstudio.com/profile/view
.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.
Recherchez l’application sous l’en-tête Applications et services dans la barre latérale gauche.
sélectionnez « Supprimer » dans la page d’inscription de l’application. Une modale s’affiche pour confirmer votre suppression.
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.