Commentaires Modifier

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

  • Article
  • 13 minutes de lecture

Pour utiliser Microsoft Graph afin de lire et d'écrire des ressources au nom d'un utilisateur, votre application doit obtenir un jeton d'accès de la plateforme d'identité Microsoft et joindre ce jeton aux demandes qu'elle envoie à Microsoft Graph. Le flux d'authentification exact à utiliser pour obtenir les jetons d'accès dépendra du type d'application que vous développez et de la possibilité d'utiliser OpenID Connect pour signer l'utilisateur dans votre application. Un flux commun 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 :

  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 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 /authorize de la plateforme d'identité Microsoft. Azure AD connectera l'utilisateur et lui demandera son consentement pour les autorisations que votre application demande. Dans le flux d'octroi de code d'autorisation, une fois le consentement obtenu, Azure AD renvoie à votre application un authorization_code qu'elle peut échanger au point de terminaison /token de la plateforme d'identité 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é 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 , qui permettront à l'application de lire le profil et le courrier de l'utilisateur connecté. L'autorisation d’accès_hors-ligne est une portée OIDC standard qui est demandée pour que l'application puisse obtenir un jeton de rafraîchissement. L'application peut utiliser le jeton de rafraîchissement 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 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é Le redirect_uri de votre application, où les réponses d’authentification peuvent être envoyées et reçues par votre application. Elle doit correspondre exactement à l’une des redirect_uris que vous avez inscrites dans le portail d’inscription des applications, sauf qu’elle doit être encodée en 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. 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 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 résultant à votre application. Peut être query ou form_post.
state Recommandé Valeur incluse dans la demande qui sera également retournée dans la réponse du jeton. Il peut s’agir d’une chaîne de tout contenu souhaité. Une valeur unique générée de manière aléatoire est généralement utilisée pour empêcher les attaques par 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.

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.

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 v2.0 de la plateforme d’identités Microsoft garantit également que l’utilisateur a accepté les autorisations indiquées dans le paramètre de requête scope. Si l’utilisateur n’a donné son consentement à aucune de ces autorisations et si un administrateur n’a pas déjà donné son consentement pour le compte de tous les utilisateurs de l’organisation, il est invité à donner son consentement aux autorisations requises.

La capture d’écran suivante est un exemple de boîte de dialogue de consentement présentée pour un utilisateur 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 demandées par votre application, la réponse contient le code d’autorisation dans le paramètre code . Voici un exemple de réponse réussie à la demande précédente. Étant donné que le paramètre response_mode dans la requête a été défini sur query, 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 Le 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 requête et la réponse sont identiques. Cette vérification permet de détecter attaques par falsification de requête intersites (CSRF) 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 scolaires
  • organizations pour les comptes professionnels ou scolaires uniquement
  • consumers pour les comptes Microsoft uniquement
  • identificateurs de client tels que l’ID de client 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.
    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. Les étendues demandées par votre application dans cette étape doivent être équivalentes ou être 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 des applications 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. 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 sont de courte durée et vous devez les actualiser après leur expiration pour continuer à accéder aux ressources. Vous pouvez le faire en envoyant une autre demande de POST au point de terminaison /token , en fournissant cette fois le refresh_token au lieu 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...
&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). Les autorisations demandées par votre application doivent être équivalentes ou être un sous-ensemble des autorisations demandées dans la demande d’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 des applications pour votre application. N’utilisez pas le secret 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

    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 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 aussi longtemps que 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 :

    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 dont votre application a besoin 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, par exemple Microsoft Graph, pour laquelle il souhaite obtenir des autorisations. Le point de terminaison ne prend pas en charge le paramètre scope.
    • Le point de terminaison Azure AD n’expose pas de point de terminaison spécifique pour le consentement de l’administrateur. Au lieu de cela, les applications utilisent 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, consultez Déclenchement de l’infrastructure de consentement Azure AD au moment de l’exécution dans Intégration d’applications à Azure Active Directory.

    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