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 :

  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 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.

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.

Boîte de dialogue de consentement pour un 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’adresse code .

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

    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 :

    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 resource paramè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 le scope paramè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