Obtenir l’accès au nom d’un utilisateur

Pour lire et écrire des ressources au nom d’un utilisateur avec Microsoft Graph, votre application doit obtenir un jeton d’accès auprès de la Plateforme d’identités Microsoft et joindre le jeton aux requêtes qu’il envoie à Microsoft Graph. Le flux d’authentification exact que vous utiliserez pour obtenir des jetons d’accès varie selon le type d’application que vous développez et selon que vous souhaitiez ou non utiliser OpenID Connect pour connecter l’utilisateur à votre application. Un flux courant utilisé par les applications natives et mobiles, et également par certaines applications web est le flux d’octroi de codes d’autorisation OAuth 2.0. Cette rubrique détaille un exemple d’utilisation de ce flux.

Étapes relatives à l’autorisation et à l’authentification

Les étapes de base nécessaires pour utiliser le flux d’octroi de codes d’autorisation OAuth 2.0 afin d’obtenir un jeton d’accès à partir du point de terminaison de la plateforme d’identités Microsoft sont les suivantes :

  1. Enregistrer votre application avec Azure AD.
  2. Obtenir l’autorisation.
  3. Obtenir un jeton d’accès.
  4. Appeler Microsoft Graph avec le jeton d’accès.
  5. Utiliser un jeton actualisé pour obtenir un nouveau jeton d’accès.

1. Inscrire votre application

Pour utiliser le point de terminaison de la plateforme d’identités Microsoft, vous devez inscrire votre application à l’aide du portail d’enregistrement d’application Azure. Pour inscrire une application, vous pouvez utiliser un compte Microsoft ou un compte scolaire ou professionnel.

Pour configurer une application qui doit utiliser le flux d’octroi de codes d’autorisation OAuth 2.0, vous devez enregistrer les valeurs suivantes lors de l’inscription de l’application :

  • L’ID de l’application (cliente) est attribué par le portail d’inscription des applications.
  • Un client (application) secret, soit un mot de passe ou une paire de clés publiques/privées (certificat). Ce n’est pas nécessaire pour les applications natives.
  • URI de redirection (ou URL de réponse) permettant à votre application de recevoir des réponses d’Azure AD.

Pour savoir comment configurer une application dans le portail Azure, consultez Inscrire votre application.

2. Obtenir l’autorisation

Pour obtenir un jeton d’accès pour plusieurs flux OpenID Connect (OIDC) et OAuth 2.0, la première étape consiste à rediriger l’utilisateur vers le point de terminaison /authorize de la Plateforme d’identités Microsoft. Azure AD va connecter l’utilisateur et demander son consentement pour les autorisations requises 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 pour User.Read et Mail.Read, ce qui permettra à l’application de lire le profil et le courrier de l’utilisateur connecté. L’autorisation pour un accès_hors connexion est une portée OIDC standard qui est demandée pour que l'application puisse obtenir un jeton actualisé, qu'elle peut utiliser 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
Parameter Obligatoire Description
client obligatoire La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les personnes qui peuvent 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 les identificateurs de client comme l’ID du client ou le nom du domaine. Pour plus de détails, reportez-vous à la rubrique Concepts de base du protocole.
client_id obligatoire ID d’application attribué par le portail d’inscription à votre application.
response_type obligatoire Doit inclure code pour le flux de codes d’autorisation.
redirect_uri recommandé URI de redirection de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Doit correspondre exactement à l’un des URI de redirection que vous avez enregistrés dans le portail d’enregistrement de l’application, sauf qu’il doit être codé au format URL. Pour les applications natives et mobiles, vous devez utiliser la valeur par défaut https://login.microsoftonline.com/common/oauth2/nativeclient.
étendue obligatoire Liste séparée par des espaces contenant des autorisations Microsoft Graph pour lesquelles vous souhaitez que l’utilisateur donne son accord. Celles-ci peuvent inclure des autorisations de ressource, telles que User.Read et Mail.Read, et 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 qui doit être utilisée pour renvoyer le jeton généré à votre application. Peut être query ou form_post.
état recommandé Valeur incluse dans la demande qui est également renvoyée dans la réponse du jeton. Il peut s’agir d’une chaîne de tout contenu de votre choix. Une valeur unique générée de façon aléatoire est généralement utilisée pour prévenir les attaques de falsification de requête intersites. L’état est également utilisé pour coder les informations sur l’état de l’utilisateur dans l’application avant la demande d’authentification, comme la page ou la vue.

Notes

Microsoft Graph expose deux types d’autorisations : d’application et déléguée. Pour les applications qui s’exécutent avec un utilisateur connecté, effectuez une demande d’autorisation déléguée dans le paramètre scope. Ces autorisations délèguent les droits de l’utilisateur connecté à votre application, lui permettant d’agir en tant qu’utilisateur connecté lorsque vous faites appel à Microsoft Graph. Pour plus d’informations sur les autorisations disponibles via Microsoft Graph, reportez-vous à la rubrique Référence d’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.

À ce stade, l’utilisateur est invité à saisir ses informations d’identification pour s’authentifier auprès de Microsoft. Le point de terminaison v2.0 de Plateforme d’identités Microsoft permet également de s’assurer que l’utilisateur a accepté les autorisations indiquées dans le paramètre de la requête scope. Si l’utilisateur n’a pas accepté l’une de ces autorisations et si un administrateur n’a pas préalablement donné son accord au nom de tous les utilisateurs de l’organisation, il lui sera demandé de donner son accord pour les autorisations requises.

Voici un exemple de boîte de dialogue de consentement affichée pour un utilisateur de compte Microsoft.

Boîte de dialogue de consentement pour un compte Microsoft

Essayez Si vous avez un compte Microsoft ou un compte professionnel ou scolaire Azure AD, vous pouvez essayer ceci en cliquant sur le lien suivant. Une fois la connexion effectuée, votre navigateur devrait être redirigé vers https://localhost/myapp/ avec un code dans la barre d’adresse.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Réponse relative à l’autorisation

Si l’utilisateur accepte les autorisations requises par votre application, la réponse contient le code d’autorisation dans le paramètre code. Voici un exemple de réponse correcte à la requête précédente. Étant donné que le paramètre response_mode dans la demande a été défini sur query, la réponse est renvoyé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 Code d’autorisation requis par l’application. L’application peut utiliser le code d’autorisation pour demander un jeton d’accès pour la ressource cible. Les codes d’autorisation ont une durée de vie très courte. En général, ils expirent au bout de 10 minutes environ.
état Si un paramètre d’état est inclus dans la demande, 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.

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 obligatoire La valeur {tenant} dans le chemin d’accès de la requête peut être utilisée pour contrôler les personnes qui peuvent 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 les identificateurs de client comme l’ID du client ou le nom du domaine. Pour plus de détails, reportez-vous à la rubrique Concepts de base du protocole.
client_id obligatoire ID d’application attribué par le portail d’inscription à votre application.
grant_type obligatoire Doit être authorization_code pour le flux de code d’autorisation.
portée obligatoire Liste d’étendues séparée par des espaces. Les étendues demandées dans cette étape doivent être équivalentes ou être un sous-ensemble d’étendues demandées dans la première étape (autorisation). Si les étendues spécifiées dans cette demande couvrent plusieurs serveurs de ressources, le point de terminaison v2.0 renvoie un jeton pour la ressource spécifiée dans la première étendue.
code obligatoire 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 de l’application que vous avez créée dans le portail d’enregistrement de l’application pour votre application. Elle ne doit pas être utilisée dans une application native, car les clés secrètes des clients ne peuvent pas être stockées en toute sécurité sur les appareils. Obligatoire pour les applications web et les API web qui ont la possibilité de stocker la clé secrète du client en toute sécurité sur le serveur web.

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. Azure AD prend uniquement en charge le type Porteur.
é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 Jeton d’accès requis. 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. Pour plus de détails, reportez-vous à la rubrique Référence au jeton v2.0.

4. Utiliser le jeton d’accès pour appeler Microsoft Graph

Après avoir obtenu 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 ont une durée de vie courte. Une fois expirés, vous devez les actualiser pour continuer à accéder aux ressources. Pour ce faire, envoyez une autre demande POST au point de terminaison /token, en fournissant cette fois le refresh_token à la place du code.

Demande

// Line breaks for legibility only

POST /common/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...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=refresh_token
&client_secret=jXoM3iz...      // NOTE: Only required for web apps
Paramètre Obligatoire Description
client_id obligatoire ID d’application attribué par le portail d’inscription à votre application.
grant_type obligatoire Doit être refresh_token.
portée obligatoire Liste séparée par des espaces contenant des autorisations (étendues). Les autorisations requises doivent être équivalentes ou être un sous-ensemble d’autorisations requises dans la demande du code d’autorisation.
refresh_token obligatoire Jeton actualisé acquis lors de la demande de jeton.
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 de l’application que vous avez créée dans le portail d’enregistrement de l’application pour votre application. Elle ne doit pas être utilisée dans une application native, car les clés secrètes des clients ne peuvent pas être stockées en toute sécurité sur les appareils. Obligatoire pour les applications web et les API web qui ont la possibilité de stocker la clé secrète du client en toute sécurité sur le serveur web.

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 Jeton d’accès requis. L’application peut utiliser ce jeton pour appeler Microsoft Graph.
token_type Indique la valeur du type de jeton. Le seul type qui prend en charge Azure AD est porteur
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 actualisé OAuth 2.0. Vous devez remplacer l’ancien jeton actualisé par ce nouveau jeton actualisé pour garantir que vos jetons actualisés restent valides le plus longtemps possible.

Scénarios de l’application pris en charge et ressources supplémentaires

Vous pouvez appeler Microsoft Graph au nom d’un utilisateur à partir des types d’applications suivants :

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 la 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 :

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 paramètre resource dans les demandes d’autorisation et de jeton pour spécifier la ressource, comme Microsoft Graph, pour lesquels il souhaite des autorisations. Le point de terminaison ne prend pas en charge le paramètre scope.
  • Le point de terminaison Azure AD ne présente pas de point de terminaison spécifique pour le consentement de l’administrateur. Au lieu d’utiliser des applications, utilisez le paramètre prompt=admin_consent dans la demande d’autorisation pour obtenir le consentement de l’administrateur pour une organisation. Pour plus d’informations, reportez-vous à la rubrique Déclenchement de l’infrastructure de consentement Azure AD lors de l’exécution dans Intégration des applications avec Azure Active Directory.

Pour plus d’informations sur l’accès à Microsoft Graph au nom d’un utilisateur à partir du point de terminaison Azure AD :

  • Pour plus d’informations sur l’utilisation du point de terminaison de la Plateforme d’identités Microsoft avec différents types d’applications, consultez les liens Prise en main de la documentation dédiée aux développeurs de la Plateforme d’identités Microsoft. La documentation contient des liens vers des rubriques de présentation, des guides de démarrage rapide, des exemples de code et une documentation relative au protocole pour différents types d’applications prises en charge par le point de terminaison de 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