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

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

Configuration requise

Avant de passer aux étapes décrites dans cet article :

1. 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.
2. Inscrivez l’application avec Microsoft Entra ID. 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 :

1. Inscrivez l’application avec Microsoft Entra ID.
2. Demander l’autorisation.
3. Demandez un jeton d’accès.
4. Utiliser le jeton d’accès pour appeler Microsoft Graph.
5. [Facultatif] Utilisez le jeton d’actualisation pour renouveler un jeton d’accès expiré.

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 centre d'administration Microsoft Entra.

À partir de l’inscription de l’application, enregistrez les valeurs suivantes :

• ID d’application (appelé ID d’objet sur le centre d'administration Microsoft Entra) 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 de Microsoft Entra ID.
• 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. Par le biais de ce point de terminaison, Microsoft Entra ID connecte l’utilisateur et demande son consentement pour les autorisations que l’application demande. Une fois le consentement obtenu, Microsoft Entra ID 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

GET 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  HTTP/1.1

curl --location --request GET 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=11111111-1111-1111-1111-111111111111&response_type=code&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=offline_access%20User.Read%20Mail.Read&state=12345'

Paramètres

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 Microsoft Entra, 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

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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d' \
--data-urlencode 'redirect_uri=https://localhost/myapp/' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_secret=zHF8Q~Krjqh4r...''

Paramètres

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

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  HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

curl --location --request GET 'https://graph.microsoft.com/v1.0/me' \
--header 'Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw' \
--data ''

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.com",
    "mobilePhone": "425-555-0101",
    "officeLocation": null,
    "preferredLanguage": "en-US",
    "surname": "Administrator",
    "userPrincipalName": "admin@contoso.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_token au lieu du code dans le corps de la demande
• En spécifiant refresh_token comme grant_type, au lieu de authorization_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

curl --location --request POST 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=11111111-1111-1111-1111-111111111111' \
--data-urlencode 'scope=User.Read Mail.Read' \
--data-urlencode 'refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=jXoM3iz...'

Paramètres

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

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 exemples de code Plateforme d'identités Microsoft.

Contenu connexe

• 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 Scénarios et flux d’authentification pris en charge.
• Choisissez parmi des 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. Consultez les didacticiels Microsoft Graph.