Utiliser Azure DevOps OAuth 2.0 pour créer une application web
Azure DevOps Services
Important
Ces informations concernent uniquement les applications OAuth Azure DevOps existantes. Les nouveaux développeurs d’applications doivent utiliser Microsoft Entra ID OAuth pour s’intégrer à Azure DevOps.
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
Accédez à l’inscription de
https://app.vsaex.visualstudio.com/app/registervotre 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 être 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=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
&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
codeparamè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 }
}
Important
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 |
|---|---|
| Type de contenu | application/x-www-form-urlencoded |
| Longueur-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 }
}
Important
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 5 ans, votre secret d’application expire. Vous êtes censé régénérer votre secret d’application pour continuer à pouvoir créer et utiliser des jetons d’accès et des jetons d’actualisation. Pour ce faire, vous pouvez cliquer sur le bouton « Régénérer le secret », qui affiche une boîte de dialogue pour confirmer que vous souhaitez effectuer cette action.
Lorsque vous confirmez que vous souhaitez régénérer, le secret d’application précédent ne fonctionnera plus et tous les jetons précédents frappés avec ce secret cesseront é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.
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 case activée pour 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’accès aux applications tierces via OAuth n’a pas été désactivé par l’administrateur de votre organisation à 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.
Q : Puis-je utiliser OAuth avec les points de terminaison SOAP et les API REST ?
R : Non. OAuth est pris en charge uniquement dans les API REST à ce stade.
Q : Comment puis-je obtenir les détails des pièces jointes pour mon élément de travail à l’aide des API REST Azure DevOps ?
R : Tout d’abord, obtenez les détails de l’élément de travail avec les éléments de travail - Obtenir l’API REST de l’élément de travail :
GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}
Pour obtenir les détails des pièces jointes, vous devez ajouter le paramètre suivant à l’URL :
$expand=all
Avec les résultats, vous obtenez la propriété relations. Vous trouverez l’URL des pièces jointes et, dans l’URL, vous trouverez l’ID. Par exemple :
$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0
$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json
$split = ($workitem.relations.url).Split('/')
$attachmentId = $split[$split.count - 1]
# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs
Articles connexes
Commentaires
Bientôt disponible : Tout au long de l’année 2024, nous abandonnerons progressivement le mécanisme de retour d’information GitHub Issues pour le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez : https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour