Obtenir l’accès au nom d’un utilisateur
Pour utiliser Microsoft Graph pour lire et écrire des ressources pour le compte d’un utilisateur, votre application doit obtenir un jeton d’accès de la Plateforme d'identités Microsoft et joindre le jeton aux demandes qu’elle envoie à Microsoft Graph. Le flux d’authentification exact à utiliser pour obtenir des jetons d’accès dépend du type d’application que vous développez et si vous souhaitez utiliser OpenID Connect pour connecter l’utilisateur à votre application. Un flux courant utilisé par les applications natives et mobiles, ainsi que par certaines applications web, est le flux d’octroi de code d’autorisation OAuth 2.0. Cet article présente un exemple d’utilisation de ce flux.
Étapes relatives à l’autorisation et à l’authentification
Voici les étapes de base pour utiliser le flux d’octroi de code d’autorisation OAuth 2.0 pour obtenir un jeton d’accès à partir du point de terminaison de la plateforme d’identités Microsoft :
- Enregistrer votre application avec Azure AD.
- Obtenir l’autorisation.
- Obtenir un jeton d’accès.
- Appeler Microsoft Graph avec le jeton d’accès.
- Utiliser un jeton actualisé pour obtenir un nouveau jeton d’accès.
1. Inscrire votre application
Pour utiliser le point de terminaison Plateforme d'identités Microsoft, vous devez inscrire votre application à l’aide du portail d’inscription d’applications Azure. Vous pouvez utiliser un compte Microsoft ou un compte professionnel ou scolaire pour inscrire une application.
Pour configurer une application afin qu’elle utilise le flux d’octroi de code d’autorisation OAuth 2.0, enregistrez les valeurs suivantes lors de l’inscription de l’application :
- ID d’application (client) attribué par le portail d’inscription de l’application.
- Clé secrète du client (application), mot de passe ou paire de clés publique/privée (certificat). La clé secrète client n’est pas requise pour les applications natives.
- URI de redirection (ou URL de réponse) permettant à votre application de recevoir des réponses de Azure AD.
Pour savoir comment configurer une application dans le portail Azure, consultez Inscrire votre application.
2. Obtenir l’autorisation
La première étape pour obtenir un jeton d’accès pour de nombreux flux OpenID Connect (OIDC) et OAuth 2.0 consiste à rediriger l’utilisateur vers le point de terminaison Plateforme d'identités Microsoft/authorize. Azure AD connecte l’utilisateur et demande son consentement pour les autorisations demandées par votre application. Dans le flux d’octroi de codes d’autorisation, une fois le consentement obtenu, Azure AD renvoie à votre application un code d’autorisation qu’elle peut échanger au niveau du point de terminaison /token de la plateforme d’identités Microsoft contre un jeton d’accès.
Demande d’autorisation
L’exemple suivant montre une demande au point de terminaison /authorize.
Avec le point de terminaison de la plateforme d’identités Microsoft, les autorisations sont demandées à l’aide du paramètre scope. Dans cet exemple, les autorisations Microsoft Graph demandées sont User.Read et Mail.Read, ce qui permet à l’application de lire le profil et le courrier de l’utilisateur connecté. 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è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 common pour les comptes Microsoft et les comptes professionnels ou scolaires, organizations pour les comptes professionnels ou scolaires uniquement, consumers pour les comptes Microsoft uniquement et pour les identificateurs de locataire tels que l’ID de locataire ou le nom de domaine. Pour plus d’informations, consultez principes de base du protocole. |
| client_id | Requis | ID d’application attribué par le portail d’inscription à votre application. |
| response_type | Requis | Doit inclure code pour le flux de codes d’autorisation. |
| redirect_uri | Recommandé | La redirect_uri de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Il doit correspondre exactement à l’une des redirect_uris que vous avez inscrites 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.Readet des étendues OIDC, telles que offline_access, qui indiquent que votre application a besoin d’un jeton d’actualisation pour un accès de longue durée aux ressources. |
| response_mode | Recommandé | Spécifie la méthode à utiliser pour renvoyer le jeton obtenu à votre application. Peut être query ou form_post. |
| état | Recommandé | Valeur incluse dans la requête qui sera é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. L’état est également utilisé pour encoder des informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, telles que la page ou la vue sur laquelle il se trouvait. |
Remarque
Microsoft Graph expose deux types d’autorisations : l’application et les autorisations déléguées. Pour les applications qui s’exécutent avec un utilisateur connecté, vous demandez des autorisations déléguées dans le scope paramètre . Ces autorisations délèguent les privilèges de l’utilisateur connecté à votre application, ce qui lui permet d’agir en tant qu’utilisateur connecté lors des appels à Microsoft Graph. Pour plus d’informations sur les autorisations disponibles via Microsoft Graph, consultez la référence autorisations.
Microsoft Graph expose également les étendues OIDC bien définies suivantes : openid, email, profileet offline_access. Les étendues OIDC address et phone ne sont pas prises en charge. Pour plus d’informations sur chaque étendue OIDC, consultez Autorisations et consentement.
Expérience relative à l’autorisation
Après avoir envoyé une demande d’autorisation, l’utilisateur est invité à entrer ses informations d’identification pour s’authentifier auprès de Microsoft. Le point de terminaison de la Plateforme d’identités Microsoft v2.0 permet également de s’assurer que l’utilisateur ait accepté les autorisations indiquées dans le paramètre de requête scope. Si l’utilisateur n’a pas donné son consentement à l’une de ces autorisations et si un administrateur n’a pas déjà donné son consentement au nom de tous les utilisateurs de l’organisation, 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.
La capture d’écran suivante est un exemple de boîte de dialogue de consentement présentée pour un utilisateur compte Microsoft.
Essayer Si vous disposez d’un compte Microsoft ou d’un compte professionnel ou scolaire Azure AD, vous pouvez l’essayer par vous-même en cliquant sur le lien suivant. Une fois connecté, votre navigateur doit être redirigé vers
https://localhost/myapp/avec un dans la barre d’adressecode.https://login.microsoftonline.com/common/oauth2/v2.0/authorize...
Réponse relative à l’autorisation
Si l’utilisateur consent aux autorisations demandées par votre 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.
GET https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d
&state=12345
| Paramètre | Description |
|---|---|
| code | Authorization_code demandé par l’application. L’application peut utiliser le code d’autorisation pour demander un jeton d’accès pour la ressource cible. Authorization_codes sont de courte durée, ils expirent généralement après environ 10 minutes. |
| state | 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 vérification 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. Obtenir un jeton
L’application utilise l’autorisation code reçue dans l’étape précédente pour demander un jeton d’accès en envoyant une demande POST au point de terminaison /token.
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=jXoM3iz... // NOTE: Only required for web apps
| 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 attribué par le portail d’inscription à votre application. |
| 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 la première étape (autorisation). Si les étendues spécifiées dans cette requête s’étendent sur 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 acquis dans la première étape du flux. |
| redirect_uri | Obligatoire | Même valeur d’URI de redirection qui a été utilisée pour acquérir le code d’autorisation. |
| 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 client_secrets ne peut pas être stocké 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
Même si le jeton d’accès est opaque dans votre application, la réponse contient une liste des autorisations pour lesquelles le jeton d’accès convient dans le paramètre scope.
{
"token_type": "Bearer",
"scope": "user.read%20Fmail.read",
"expires_in": 3600,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
| 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 contenant des autorisations Microsoft Graph pour lesquelles le jeton d’accès est valide. |
| expires_in | Validité du jeton d’accès (en secondes). |
| access_token | Le jeton d'accès demandé. Votre application peut utiliser ce jeton pour appeler Microsoft Graph. |
| refresh_token | Jeton d’actualisation OAuth 2.0. Votre application peut utiliser ce jeton pour acquérir des jetons d’accès supplémentaires après l’expiration du jeton d’accès en cours. 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, vous pouvez l’utiliser pour appeler Microsoft Graph en l’incluant dans l’en-tête Authorization d’une requête. La requête suivante obtient le profil de l’utilisateur connecté.
GET https://graph.microsoft.com/v1.0/me
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Une réponse correcte est semblable à celle-ci (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",
"id":"12345678-73a6-4952-a53a-e9916737ff7f",
"businessPhones":[
"+1 555555555"
],
"displayName":"Chris Green",
"givenName":"Chris",
"jobTitle":"Software Engineer",
"mail":null,
"mobilePhone":"+1 5555555555",
"officeLocation":"Seattle Office",
"preferredLanguage":null,
"surname":"Green",
"userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}
5. Utiliser le jeton actualisé pour obtenir un nouveau jeton d’accès
Les jetons d’accès sont de courte durée et vous devez les actualiser après leur expiration pour continuer à accéder aux ressources. Pour ce faire, envoyez une autre POST demande au /token point de terminaison, en fournissant cette fois au refresh_token lieu du 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ètre | Obligatoire | Description |
|---|---|---|
| client_id | Requis | ID d’application attribué par le portail d’inscription à votre application. |
| 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 authorization_code d’origine. |
| refresh_token | Requis | Jeton actualisé acquis lors de la demande de jeton. |
| 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 correcte relative au jeton doit se présenter comme suit.
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "user.read%20mail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
| 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. |
Scénarios de l’application pris en charge et ressources supplémentaires
Vous pouvez appeler Microsoft Graph pour le compte d’un utilisateur à partir des types d’applications suivantes :
- Applications natives/mobiles
- Applications web
- Applications à page unique (SPA)
- API web de back end : par exemple, dans les cas où une application cliente, telle qu’une application native, implémente des fonctionnalités dans un back end d’API web. Avec le point de terminaison Plateforme d'identités Microsoft, l’application cliente et l’API web principale doivent avoir le même ID d’application.
Pour plus d’informations sur les scénarios d’applications prises en charge avec le point de terminaison de la Plateforme d’identités Microsoft, consultez la page Flux d’authentification et scénarios d’applications.
Remarque : le fait d’appeler Microsoft Graph à partir d’une API web autonome n’est actuellement pas pris en charge par le point de terminaison de plateforme d’identités Microsoft. Dans ce scénario, vous devez utiliser le point de terminaison Azure AD.
Pour plus d’informations sur l’accès à Microsoft Graph au nom d’un utilisateur à partir du point de terminaison de plateforme d’identités Microsoft :
- Pour accéder aux liens vers la documentation relative au protocole et vers les articles de prise en main des différents types d’applications, reportez-vous à la rubrique Documentation relative au point de terminaison de plateforme d’identités Microsoft.
- Pour des explications détaillées sur les types d’applications et les flux d’authentification pris en charge, consultez la page Types d’applications v2.0.
- Pour plus d’informations sur les bibliothèques d’authentification recommandées et l’intergiciel serveur pour la plateforme d’identités Microsoft, consultez Azure Active Directory bibliothèques d’authentification v2.0.
Remarques relatives au point de terminaison
Microsoft continue de prendre en charge le point de terminaison Azure AD. Plusieurs différences existent entre le point de terminaison de la Plateforme d’identités Microsoft et le point de terminaison Azure AD. Lorsque vous utilisez le point de terminaison Azure AD :
- Votre application requiert un ID d’application (ID client) différent pour chaque plateforme.
- Si votre application est une application multi-clients, vous devez la configurer explicitement pour qu’elle soit multi-clients au niveau du portail Azure.
- Toutes les autorisations requises par votre application doivent être configurées par le développeur. Le point de terminaison Azure AD ne prend pas en charge le consentement dynamique (incrémentiel).
- Le point de terminaison Azure AD utilise un
resourceparamètre dans les demandes d’autorisation et de jeton pour spécifier la ressource, telle que Microsoft Graph, pour laquelle il souhaite obtenir des autorisations. Le point de terminaison ne prend pas en charge lescopeparamètre .
Pour plus d’informations sur l’accès à Microsoft Graph pour le compte d’un utilisateur, consultez les ressources suivantes.
- Pour plus d’informations sur l’utilisation de la Plateforme d’identités Microsoft avec différents types d’applications, consultez les liens Prise en main de la documentation sur la Plateforme d’identités Microsoft.
- Pour plus d’informations sur la bibliothèque d’authentification Microsoft (MSAL) et le middleware serveur disponibles pour une utilisation avec le point de terminaison de la Plateforme d’identités Microsoft, consultez la page Bibliothèques d’authentification Microsoft.
Voir aussi
- Découvrez comment créer une application web qui appelle Microsoft Graph pour le compte d’un utilisateur.
- Pour obtenir des exemples d’utilisation de la Plateforme d’identités Microsoft pour sécuriser différents types d’application, consultez l’article Exemples de code de la plateforme d’identités Microsoft (point de terminaison v2.0).
- Comportement de l’invite dans les demandes interactives MSAL.js