Obtenir l’accès au nom d’un utilisateur
Cet article fait partie d’une série sur l’authentification et l’autorisation pour Microsoft Graph via le Plateforme d'identités Microsoft. L’article précédent est Inscrire une application avec le Plateforme d'identités Microsoft.
Pour appeler Microsoft Graph, une application doit obtenir un jeton d’accès auprès du Plateforme d'identités Microsoft. Ce jeton d’accès inclut des informations indiquant si l’application est autorisée à accéder à Microsoft Graph pour le compte d’un utilisateur connecté ou avec sa propre identité. Cet article fournit des conseils sur la façon dont une application peut accéder à Microsoft Graph pour le compte d’un utilisateur, également appelé accès délégué.
Cet article détaille les requêtes HTTP brutes impliquées pour qu’une application obtienne l’accès au nom d’un utilisateur à l’aide d’un flux populaire appelé flux d’octroi de code d’autorisation OAuth 2.0. Vous pouvez également éviter d’écrire des requêtes HTTP brutes et utiliser une bibliothèque d’authentification intégrée ou prise en charge par Microsoft qui gère un grand nombre de ces détails pour vous et vous aide à obtenir des jetons d’accès et à appeler Microsoft Graph. Pour plus d’informations, consultez Utiliser la bibliothèque d’authentification Microsoft (MSAL).
Conditions préalables
Avant de passer aux étapes décrites dans cet article :
- Comprendre les concepts d’authentification et d’autorisation dans le Plateforme d'identités Microsoft. Pour plus d’informations, consultez Principes de base de l’authentification et de l’autorisation.
- Inscrivez l’application auprès d’Azure AD. Pour plus d’informations, consultez Inscrire une application avec le Plateforme d'identités Microsoft.
Étapes relatives à l’autorisation et à l’authentification
Pour qu’une application obtienne l’autorisation et l’accès à Microsoft Graph à l’aide du flux de code d’autorisation, vous devez suivre les cinq étapes suivantes :
- Inscrivez l’application auprès d’Azure AD.
- Demander l’autorisation.
- Demandez un jeton d’accès.
- Utiliser le jeton d’accès pour appeler Microsoft Graph.
- [Facultatif] Utilisez le jeton d’actualisation pour renouveler un jeton d’accès expiré.
Conseil
Essayez les étapes 2 à 5 dans Postman. N’oubliez pas de remplacer les jetons et les ID !
1. Inscrire l’application
Avant que l’application puisse appeler les points de terminaison Plateforme d'identités Microsoft ou Microsoft Graph, elle doit être correctement inscrite. Suivez les étapes pour inscrire votre application sur le Portail Azure.
À partir de l’inscription de l’application, enregistrez les valeurs suivantes :
- ID d’application (ID d’objet) attribué par le portail d’inscription d’application.
- URI de redirection (ou URL de réponse) pour que l’application reçoive des réponses d’Azure AD.
- Une clé secrète client (mot de passe d’application), un certificat ou des informations d’identification d’identité fédérée. Cette propriété n’est pas nécessaire pour les clients publics tels que les applications natives, mobiles et monopage.
2. Demander l’autorisation
La première étape du flux de code d’autorisation consiste pour l’utilisateur à autoriser l’application à agir en son nom.
Dans le flux, l’application redirige l’utilisateur vers le point de terminaison Plateforme d'identités Microsoft/authorize. Via ce point de terminaison, Azure AD connecte l’utilisateur et demande son consentement pour les autorisations que l’application demande. Une fois le consentement obtenu, Azure AD retourne un code d’autorisation à l’application. L’application peut ensuite échanger ce code sur le point de terminaison Plateforme d'identités Microsoft /token contre un jeton d’accès.
Demande d’autorisation
L’exemple suivant montre une requête au point de /authorize terminaison.
Dans l’URL de la requête, vous appelez le point de /authorize terminaison et spécifiez les propriétés requises et recommandées en tant que paramètres de requête.
Dans l’exemple suivant, l’application demande les autorisations Microsoft Graph User.Read et Mail.Read , qui permettent à l’application de lire le profil et le courrier de l’utilisateur connecté, respectivement. L’autorisation offline_access est une étendue OIDC standard demandée afin que l’application puisse obtenir un jeton d’actualisation. L’application peut utiliser le jeton d’actualisation pour obtenir un nouveau jeton d’accès lorsque le jeton actuel expire.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345
Paramètres
| Paramètre | Obligatoire | Description |
|---|---|---|
| client | Requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler qui peut se connecter à l’application. Les valeurs autorisées sont les suivantes :common pour les comptes Microsoft et les comptes professionnels ou scolairesorganizations pour les comptes professionnels ou scolaires uniquementconsumers pour les comptes Microsoft uniquementPour plus d’informations, consultez Principes de base du protocole. |
| client_id | Requis | ID d’application (client) attribué par le portail d’inscription à l’application. Également appelé appId dans l’application Microsoft Graph et l’objet principal de service. |
| response_type | Requis | Doit inclure code pour le flux de code d’autorisation OAuth 2.0. |
| redirect_uri | Recommandé | URI de redirection de l’application, où les réponses d’authentification sont envoyées et reçues par l’application. Il doit correspondre exactement à l’un des URI de redirection que vous avez enregistrés dans le portail d’inscription d’application, sauf qu’il doit être codé url. Pour les applications natives et mobiles, vous devez utiliser la valeur par défaut de https://login.microsoftonline.com/common/oauth2/nativeclient. |
| étendue | Requis | Liste séparée par des espaces contenant des autorisations Microsoft Graph pour lesquelles vous souhaitez que l’utilisateur donne son accord. N’encodez pas les espaces en pourcentage. Ces autorisations peuvent inclure des autorisations de ressources, telles que User.Read et Mail.Read, et des étendues OIDC, telles que offline_access, qui indiquent que l’application a besoin d’un jeton d’actualisation pour un accès durable aux ressources. |
| response_mode | Recommandé | Spécifie la méthode qui doit être utilisée pour renvoyer le jeton obtenu à l’application. Peut être query ou form_post. |
| state | Recommandé | Valeur incluse dans la requête qui est également retournée dans la réponse du jeton. Il peut s’agir d’une chaîne de n’importe quel contenu que vous souhaitez. Une valeur unique générée de manière aléatoire est généralement utilisée pour empêcher les attaques de falsification de requête intersites. Cette propriété est également utilisée pour encoder des informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, telles que la page ou l’affichage sur lequel il se trouve. |
Expérience de consentement de l’utilisateur
Une fois que l’application a envoyé la demande d’autorisation, l’utilisateur est invité à entrer ses informations d’identification pour s’authentifier auprès de Microsoft. Le point de terminaison Plateforme d'identités Microsoft v2.0 garantit que l’utilisateur a consenti aux autorisations indiquées dans le paramètre de scope requête. S’il existe une autorisation pour laquelle l’utilisateur ou l’administrateur n’a pas donné son consentement, il est invité à donner son consentement pour les autorisations requises. Pour plus d’informations sur l’expérience de consentement Azure AD, consultez Expérience de consentement d’application et Présentation des autorisations et du consentement.
La capture d’écran suivante est un exemple de boîte de dialogue de consentement présentée pour un utilisateur compte Microsoft.
Réponse relative à l’autorisation
Si l’utilisateur consent aux autorisations demandées par l’application, la réponse contient le code d’autorisation dans le code paramètre . Voici un exemple de réponse réussie à la requête précédente. Étant donné que le response_mode paramètre de la requête a la queryvaleur , la réponse est retournée dans la chaîne de requête de l’URL de redirection.
HTTP/1.1 200 OK
https://localhost/myapp/?code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d&state=12345&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#
Paramètres de requête
| Paramètre | Description |
|---|---|
| code | Code d’autorisation demandé par l’application. L’application utilise le code d’autorisation pour demander un jeton d’accès pour la ressource cible. Les codes d’autorisation sont de courte durée et expirent généralement au bout de 10 minutes environ. |
| état | Si un paramètre d’état est inclus dans la requête, la même valeur doit apparaître dans la réponse. L’application doit vérifier que les valeurs d’état dans la demande et la réponse sont identiques. Cette case activée permet de détecter les attaques csrf (Cross-Site Request Forgery) contre le client. |
| session_state | Valeur unique qui identifie la session utilisateur active. Cette valeur est un GUID, mais elle doit être traitée comme une valeur opaque qui est passée sans examen. |
3. Demander un jeton d’accès
L’application utilise l’autorisation code reçue à l’étape précédente pour demander un jeton d’accès en envoyant une POST requête au point de /token terminaison.
Demande de jeton
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=HF8Q~Krjqh4r... // NOTE: Only required for web apps
Paramètres
| Paramètre | Obligatoire | Description |
|---|---|---|
| client | Requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler qui peut se connecter à l’application. Les valeurs autorisées sont les suivantes :common pour les comptes Microsoft et les comptes professionnels ou scolairesorganizations pour les comptes professionnels ou scolaires uniquementconsumers pour les comptes Microsoft uniquementPour plus d’informations, consultez Principes de base du protocole. |
| client_id | Requis | ID d’application (client) attribué par le portail d’inscription à l’application. Également appelé appId dans l’application Microsoft Graph et l’objet principal de service. |
| grant_type | Requis | Doit être authorization_code pour le flux de code d’autorisation. |
| portée | Requis | Liste d’étendues séparées par des espaces. N’encodez pas les espaces en pourcentage. Les étendues que votre application demande dans cette étape doivent être équivalentes ou un sous-ensemble des étendues qu’elle a demandées dans le volet d’autorisation à l’étape 2. Si les étendues spécifiées dans cette requête couvrent plusieurs serveurs de ressources, le point de terminaison v2.0 retourne un jeton pour la ressource spécifiée dans la première étendue. |
| code | Requis | Code d’autorisation que vous avez acquis dans la partie d’autorisation à l’étape 2. |
| redirect_uri | Obligatoire | La même valeur d’URI de redirection que celle utilisée pour acquérir le code d’autorisation à l’étape 2. |
| client_secret | Obligatoire pour les applications web | Clé secrète client que vous avez créée dans le portail d’inscription de l’application pour votre application. Il ne doit pas être utilisé dans une application native, car les secrets client ne peuvent pas être stockés de manière fiable sur les appareils. Elle est requise pour les applications web et les API web, qui ont la possibilité de stocker les client_secret en toute sécurité côté serveur. |
Réponse du jeton
Le jeton d’accès contient une liste des autorisations pour lesquelles le jeton d’accès est approprié dans le scope paramètre . La réponse est similaire à l’exemple suivant.
HTTP/1.1 200 OK
Content-type: application/json
{
"token_type": "Bearer",
"scope": "Mail.Read User.Read",
"expires_in": 3736,
"ext_expires_in": 3736,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
Propriétés du corps de la réponse
| Paramètre | Description |
|---|---|
| token_type | Indique la valeur du type de jeton. Le seul type pris en charge par Azure AD est Bearer. |
| étendue | Liste séparée par des espaces des autorisations Microsoft Graph pour lesquelles le jeton d’accès est valide. |
| expires_in | Validité du jeton d’accès (en secondes). |
| ext_expires_in | Indique une durée de vie étendue pour le jeton d’accès (en secondes) et utilisée pour prendre en charge la résilience lorsque le service d’émission de jeton ne répond pas. |
| access_token | Le jeton d'accès demandé. L’application peut utiliser ce jeton pour appeler Microsoft Graph. |
| refresh_token | Jeton d’actualisation OAuth 2.0. L’application peut utiliser ce jeton pour acquérir des jetons d’accès supplémentaires après l’expiration du jeton d’accès actuel. Les jetons d’actualisation ont une longue durée de vie. Ils peuvent être utilisés pour conserver l’accès à des ressources pour une période prolongée. Un jeton d’actualisation n’est retourné que si offline_access a été inclus en tant que scope paramètre. Pour plus d’informations, consultez les informations de référence sur les jetons v2.0. |
4. Utiliser le jeton d’accès pour appeler Microsoft Graph
Une fois que vous disposez d’un jeton d’accès, l’application l’utilise pour appeler Microsoft Graph en attachant le jeton d’accès en tant que jeton du porteur à l’en-tête Authorization dans une requête HTTP. La requête suivante obtient le profil de l’utilisateur connecté.
Demande
GET https://graph.microsoft.com/v1.0/me
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Réponse
Une réponse réussie ressemble à ce qui suit (certains en-têtes de réponse ont été supprimés).
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [
"425-555-0100"
],
"displayName": "MOD Administrator",
"givenName": "MOD",
"jobTitle": null,
"mail": "admin@contoso.OnMicrosoft.com",
"mobilePhone": "425-555-0101",
"officeLocation": null,
"preferredLanguage": "en-US",
"surname": "Administrator",
"userPrincipalName": "admin@contoso.onmicrosoft.com",
"id": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
}
5. Utiliser le jeton d’actualisation pour renouveler un jeton d’accès expiré
Les jetons d’accès sont de courte durée et l’application doit les actualiser après leur expiration pour continuer à accéder aux ressources. Pour ce faire, l’application envoie une autre POST demande au point de /token terminaison, cette fois :
- Fournir le
refresh_tokenau lieu du code dans le corps de la demande - En spécifiant
refresh_tokencomme grant_type, au lieu deauthorization_code.
Demande
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11111111-1111-1111-1111-111111111111
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=jXoM3iz... // NOTE: Only required for web apps
Paramètres
| Paramètre | Obligatoire | Description |
|---|---|---|
| client | Requis | La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler qui peut se connecter à l’application. Les valeurs autorisées sont les suivantes :common pour les comptes Microsoft et les comptes professionnels ou scolairesorganizations pour les comptes professionnels ou scolaires uniquementconsumers pour les comptes Microsoft uniquementPour plus d’informations, consultez Principes de base du protocole. |
| client_id | Requis | ID d’application (client) attribué par le portail d’inscription à votre application. Également appelé appId dans l’application Microsoft Graph et l’objet principal de service. |
| grant_type | Requis | Doit être refresh_token. |
| portée | Facultatif | Liste d’autorisations séparées par des espaces (étendues). N’encodez pas les espaces en pourcentage. Les autorisations demandées par votre application doivent être équivalentes ou un sous-ensemble des autorisations qu’elle a demandées dans la demande de code d’autorisation d’origine à l’étape 2. |
| refresh_token | Requis | Les refresh_token que votre application a acquises lors de la demande de jeton à l’étape 3. |
| client_secret | Obligatoire pour les applications web | Clé secrète client que vous avez créée dans le portail d’inscription de l’application pour votre application. N’utilisez pas le secret dans une application native, car client_secrets ne peuvent pas être stockés de manière fiable sur les appareils. Elle est requise pour les applications web et les API web, qui ont la possibilité de stocker les client_secret en toute sécurité côté serveur. |
Réponse
Une réponse de jeton réussie ressemble à ce qui suit.
HTTP/1.1 200 OK
Content-type: application/json
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "Mail.Read User.Read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
Paramètres du corps de la réponse
| Paramètre | Description |
|---|---|
| access_token | Le jeton d'accès demandé. L’application peut utiliser ce jeton dans les appels à Microsoft Graph. |
| token_type | Indique la valeur du type de jeton. Le seul type pris en charge par Azure AD est Bearer. |
| expires_in | Validité du jeton d’accès (en secondes). |
| portée | Autorisations (étendues) pour lesquelles le jeton actualisé est valide. |
| refresh_token | Nouveau jeton d’actualisation OAuth 2.0. Remplacez l’ancien jeton d’actualisation par ce jeton d’actualisation nouvellement acquis pour vous assurer que vos jetons d’actualisation restent valides le plus longtemps possible. |
Ressources supplémentaires
Vous pouvez appeler Microsoft Graph au nom d’un utilisateur à partir de différents types d’applications, comme les applications monopage, les applications web et les applications mobiles. Pour plus d’informations, consultez Flux d’authentification et scénarios d’application.
En plus du flux d’octroi de code d’autorisation OAuth 2.0, le Plateforme d'identités Microsoft prend en charge différents flux d’authentification pour les scénarios d’accès délégué et d’accès d’application uniquement. Pour plus d’informations, consultez Scénarios et flux d’authentification pris en charge.
Utiliser la bibliothèque d’authentification Microsoft (MSAL)
Dans cet article, vous avez parcouru les détails du protocole de bas niveau généralement requis uniquement lors de la création manuelle et de l’émission de requêtes HTTP brutes pour exécuter le flux de code d’autorisation. Dans les applications de production, utilisez une bibliothèque d’authentification intégrée ou prise en charge par Microsoft, telle que la bibliothèque d’authentification Microsoft (MSAL), pour obtenir des jetons de sécurité et appeler des API web protégées telles que Microsoft Graph.
MSAL et d’autres bibliothèques d’authentification prises en charge simplifient le processus en gérant des détails tels que la validation, la gestion des cookies, la mise en cache des jetons et les connexions sécurisées, ce qui vous permet de vous concentrer sur les fonctionnalités de votre application.
Microsoft a créé et gère un large éventail d’exemples de code qui illustrent l’utilisation des bibliothèques d’authentification prises en charge avec les Plateforme d'identités Microsoft. Pour accéder à ces exemples de code, consultez les étapes suivantes.
Étapes suivantes
Cet article fait partie de la série suivante d’articles sur l’authentification et l’autorisation pour Microsoft Graph via le Plateforme d'identités Microsoft.
- Article 1 : Principes de base de l’authentification et de l’autorisation
- Article 2 : Inscrire une application auprès du Plateforme d'identités Microsoft
- Article 3 : Obtenir l’accès au nom d’un utilisateur
- Article 4 : Obtenir l’accès sans utilisateur
Ensuite, choisissez parmi les exemples de code générés et gérés par Microsoft pour exécuter des applications personnalisées qui utilisent des bibliothèques d’authentification prises en charge, connectez des utilisateurs et appelez Microsoft Graph.