Obtenir l’accès sans utilisateur

Certaines applications appellent Microsoft Graph avec leur propre identité et non au nom d’un utilisateur. Dans de nombreux cas, il s’agit de démons ou de services d’arrière-plan qui s’exécutent sur un serveur sans la présence d’un utilisateur connecté. Un exemple d’une telle application peut être un service d’archivage de messagerie qui est activé et s’exécute pendant la nuit. Dans certains cas, les applications auxquelles un utilisateur est connecté doivent également appeler Microsoft Graph sous leur propre identité. Par exemple, une application peut avoir besoin d’utiliser une fonctionnalité qui requiert des privilèges plus élevés que ceux de l’utilisateur connecté.

Les applications qui appellent Microsoft Graph avec leur propre identité utilisent le flux d’octroi d’informations d’identification du client OAuth 2.0 pour obtenir des jetons d’accès auprès d’Azure Active Directory. Cette rubrique décrit les étapes de base permettant de configurer un service et d’utiliser le flux d’octroi d’informations d’identification du client OAuth pour obtenir un jeton d’accès.

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

Voici les étapes de base nécessaires à la configuration d’un service et à l’obtention d’un jeton auprès du point de terminaison de la Plateforme d’identités Microsoft afin que votre service puisse appeler Microsoft Graph sous sa propre identité :

  1. Inscrire votre application
  2. Configurer les autorisations pour Microsoft Graph sur votre application.
  3. Obtenir l’accord de l’administrateur.
  4. Obtenir un jeton d’accès.
  5. Utiliser le jeton d’accès pour appeler Microsoft Graph.

1. Inscrire votre application

Pour vous authentifier au point de terminaison de la Plateforme d’identités Microsoft, vous devez d’abord inscrire votre application sur le portail d’enregistrement des applications Azure. Pour ce faire, vous pouvez utiliser un compte Microsoft ou un compte scolaire ou professionnel.

Pour un service qui appelle Microsoft Graph sous sa propre identité, vous devez inscrire votre application pour la plateforme web et copier les valeurs suivantes :

  • ID d’application attribué par le portail d’enregistrement des applications Azure.
  • Clé secrète du client (application) : mot de passe ou paire clé publique/clé privée (certificat).
  • URL de redirection pour que votre service reçoive les réponses des jetons.
  • URL de redirection pour que votre service reçoive les réponses relatives au consentement de l’administrateur si votre application implémente une fonctionnalité permettant de demander le consentement de l’administrateur.

Pour savoir comment configurer une application à l’aide du portail d’enregistrement des applications Azure, consultez Inscrire votre application.

Avec le flux d’octroi d’informations d’identification du client OAuth 2.0, votre application s’authentifie directement au point de terminaison /token de la Plateforme d’identités Microsoft à l’aide de l’ID d’application attribué par Azure AD et de la clé secrète que vous créez sur le portail.

2. Configurer les autorisations pour Microsoft Graph

Pour les applications qui appellent Microsoft Graph sous leur propre identité, Microsoft Graph expose les autorisations de l’application (Microsoft Graph peut également exposer des autorisations déléguées pour les applications qui l’appellent au nom d’un utilisateur). Vous préconfigurez les autorisations d’application requises par votre application lorsque vous l’inscrivez. Les autorisations de l’application nécessitent toujours l’autorisation de l’administrateur. Un administrateur peut accorder ces autorisations à l’aide du portail Azure lorsque votre application est installée dans l’organisation. Vous pouvez également permettre l’enregistrement dans votre application via laquelle les administrateurs peuvent accorder les autorisations que vous avez configurées. Une fois l’autorisation de l’administrateur enregistrée par Azure AD, votre application peut demander des jetons sans avoir à demander à nouveau une autorisation. Pour plus d’informations sur les autorisations disponibles avec Microsoft Graph, consultez la rubrique Référence d’autorisations

Pour configurer les autorisations relatives à votre application sur le portail des enregistrements des applications Azure : dans la page Autorisations d’API de l’application, choisissez Ajouter une autorisation, sélectionnez Microsoft Graph, puis choisissez les autorisations dont votre application a besoin sous Autorisations d’application.

La capture d’écran suivante illustre la boîte de dialogue Sélectionner les autorisations pour les autorisations de l’application Microsoft Graph.

Sélectionnez la boîte de dialogue Autorisations pour les autorisations de l’application Microsoft Graph.

Remarque : nous vous recommandons de configurer l’ensemble d’autorisations requises par votre application, avec le moins de privilèges possible. Cette expérience est beaucoup plus confortable pour les administrateurs que d’avoir à accorder une longue liste d’autorisations.

Un administrateur peut accorder les autorisations dont votre application a besoin sur le portail Azure. Toutefois, il est souvent préférable de fournir aux administrateurs une expérience d’inscription à l’aide du point de terminaison /adminconsent de la Plateforme d’identités Microsoft.

Important : à chaque fois que vous modifiez les autorisations configurées, vous devez à nouveau obtenir le consentement de l’administrateur. Les modifications apportées dans le portail d’inscription des applications prennent effet uniquement lorsque le consentement a été donné par l’administrateur du client.

Demande

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions
Paramètre Condition Description
client Requis Client du répertoire auquel vous souhaitez demander l’autorisation. Il peut s’agir du format GUID ou d’un format de nom convivial. Si vous ne savez pas à quel client appartient l’utilisateur et que vous souhaitez qu’il se connecte avec n’importe quel client, utilisez common.
client_id Obligatoire ID d’application que le portail d’enregistrement des applications Azure a attribué à votre application.
redirect_uri Obligatoire URI de redirection où vous souhaitez que la réponse soit envoyée. Doit correspondre exactement à l’un des URI de redirection que vous avez enregistrés dans le portail, sauf qu’il doit être au format URL et qu’il peut avoir des segments de chemin supplémentaires.
state 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. L’état est 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.

En envoyant des demandes au point de terminaison /adminconsent, Azure AD veille à ce que seul un administrateur client puisse se connecter pour effectuer la demande. L’administrateur est invité à approuver toutes les autorisations d’application que vous avez demandées pour votre application dans le portail d’enregistrement de l’application.

Voici un exemple de boîte de dialogue d’autorisation présentée par Azure AD à l’administrateur :

Boîte de dialogue relative à l’autorisation de l’administrateur.

Réponse

Si l’administrateur approuve les autorisations relatives à votre application, la réponse réussie ressemble à ceci :

// Line breaks are for legibility only.

GET https://localhost/myapp/permissions
?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=12345
&admin_consent=True
Paramètre Description
client Client du répertoire ayant accordé à votre application les autorisations demandées au format GUID.
state 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. L’état est 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.
admin_consent Défini sur True.

Essayer : vous pouvez faire un essai en collant la demande suivante dans un navigateur. Si vous vous connectez en tant qu’administrateur général pour un client Azure AD, la boîte de dialogue relative au consentement de l’administrateur pour l’application s’affiche. (Il s’agit d’une application différente de celle de la capture d’écran de la boîte de dialogue de consentement affichée plus haut.)

https://login.microsoftonline.com/common/adminconsent?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&state=12345&redirect_uri=https://localhost/myapp/permissions

4. Obtenir un jeton d’accès

Dans le flux d’octroi d’informations d’identification du client OAuth 2.0, utilisez l’ID d’application et la clé secrète que vous avez enregistrés lors de l’inscription de votre application pour demander un jeton d’accès directement auprès du point de terminaison /token de la Plateforme d’identités Microsoft.

Spécifiez les autorisations préconfigurées en transmettant https://graph.microsoft.com/.default comme valeur pour le paramètre scope dans la demande de jeton. Reportez-vous à la description du paramètre scope dans la demande de jeton ci-dessous pour plus de détails.

Demande de jeton

Envoyez une requête POST au point de terminaison /token de la Plateforme d’identités pour acquérir un jeton d’accès :

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
Paramètre Condition Description
client Obligatoire Client du répertoire auquel vous souhaitez demander l’autorisation. Il peut s’agir du format GUID ou d’un format de nom convivial.
client_id Obligatoire ID d’application attribué par le portail d’enregistrement des applications Azure lorsque vous avez inscrit votre application.
étendue Requis La valeur transmise pour le paramètre scope dans cette demande doit être l’identificateur (URI de l’ID d’application) de la ressource souhaitée, avec le suffixe .default. Pour Microsoft Graph, la valeur est https://graph.microsoft.com/.default. Cette valeur informe le point de terminaison de la Plateforme d’identités Microsoft que parmi toutes les autorisations que vous avez configurées pour votre application dans le portail d’inscription de l’application, un jeton doit être généré pour celles associées à la ressource que vous souhaitez utiliser.
client_secret Requis Clé secrète de l’application que vous avez générée pour votre application dans le portail d’enregistrement de l’application. Dans la formation basée sur des scénarios.
grant_type Requis Doit être client_credentials.

Réponse du jeton

Une réponse correcte se présente comme suit :

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
Paramètre Description
access_token Jeton d’accès requis. Votre application peut utiliser ce jeton pour passer des 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).

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

Une fois que vous disposez du jeton d’accès, vous pouvez l’utiliser pour appeler Microsoft Graph en l’incluant dans l’en-tête Authorization d’une demande. La demande suivante obtient le profil d’un utilisateur spécifique. Votre application doit avoir l’autorisation User.Read.All pour appeler cette API.

GET https://graph.microsoft.com/v1.0/users/12345678-73a6-4952-a53a-e9916737ff7f
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

Une réponse correcte sera 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: 309.0273
Date: Wed, 26 Apr 2017 19:53:49 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"
}

Scénarios d’application pris en charge et ressources

Les applications qui appellent Microsoft Graph sous leur propre identité sont classées en deux catégories :

  • Les services d’arrière-plan (démons) qui s’exécutent sur un serveur sans qu’un utilisateur soit connecté.
  • Les applications auxquelles un utilisateur est connecté, mais qui appellent également Microsoft Graph avec leur propre identité ; par exemple, pour utiliser une fonctionnalité qui requiert des privilèges plus élevés que ceux de l’utilisateur.

Les applications qui appellent Microsoft Graph avec leur propre identité utilisent le flux d’octroi d’informations d’identification de client OAuth 2.0 pour s’authentifier auprès d’Azure Active Directory et obtenir un jeton. Pour le point de terminaison de la Plateforme d’identités Microsoft, vous pouvez explorer ce scénario davantage avec les ressources suivantes :

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 :

  • Si votre application est une application mutualisée, vous devez la configurer explicitement comme une application mutualisée sur le portail Azure.
  • Il n’existe pas de point de terminaison de consentement de l’administrateur (/adminconsent). Mais votre application peut demander le consentement de l’administrateur lors de l’exécution en ajoutant le paramètre prompt=admin_consent à une demande d’autorisation. 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.
  • Les paramètres des demandes d’autorisation et de jeton sont différents. Par exemple, il n’y a pas de paramètre scope dans les demandes de point de terminaison Azure AD. En revanche, le paramètre resource permet de spécifier l’URI de la ressource (resource=https://graph.microsoft.com) pour laquelle l’autorisation (pour le consentement de l’administrateur) ou un jeton est demandé.

Vous pouvez explorer ce scénario plus en détail avec 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. Le guide 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 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