Plateforme d’identités Microsoft et flux d’informations d’identification du client OAuth 2.0

Le flux d’octroi des informations d’identification du client OAuth 2.0 permet à un service web (client confidentiel) d’utiliser ses propres informations d’identification pour s’authentifier lorsqu’il appelle un autre service web, au lieu d’emprunter l’identité d’un utilisateur. L’octroi spécifié dans RFC 6749, parfois appelé OAuth à deux branches, peut être utilisé pour accéder à des ressources hébergées sur le web à l’aide de l’identité d’une application. Ce type est le plus souvent utilisé pour les interactions de serveur à serveur qui doivent s’exécuter en arrière-plan, sans interaction immédiate avec un utilisateur, et est souvent appelé démons ou comptes de service.

Dans le flux des informations d’identification du client, les autorisations sont accordées directement à l’application elle-même par l’administrateur. Lorsque l’application présente un jeton à une ressource, la ressource impose que l’application elle-même, et non pas l'utilisateur (puisqu’il n’est pas impliqué, ait l’autorisation d’effectuer une action. Cet article décrit les deux étapes nécessaires pour :

• Autoriser une application à appeler une API
• Comment obtenir les jetons nécessaires pour appeler cette API.

Cet article explique comment programmer directement par rapport au protocole dans votre application. Dans la mesure du possible, nous vous recommandons d’utiliser les bibliothèques d’authentification Microsoft (MSAL) prises en charge au lieu d’acquérir des jetons et d’appeler des API web sécurisées. Vous pouvez également vous reporter à des exemples d’applications utilisant MSAL. Remarquez que les jetons d’actualisation ne seront jamais accordés avec ce flux, car client_id et client_secret (qui seraient nécessaires pour obtenir un jeton d’actualisation) peuvent être utilisés pour obtenir un jeton d’accès à la place.

Pour augmenter le niveau d’assurance, la plateforme d’identités Microsoft permet également au service appelant de s’authentifier à l’aide d’un certificat ou d’informations d’identification fédérées au lieu d’un secret partagé. Étant donné que les propres informations d’identification de l’application sont utilisées, ces informations d’identification doivent être conservées en toute sécurité. Ne jamais publier ces informations d’identification dans votre code source, les incorporer dans des pages web ou les utiliser dans une application native largement distribuée.

Schéma de protocole

Le flux d’informations d’identification client complet est similaire à l’illustration suivante. Nous décrirons en détail chacune des étapes plus loin dans cet article.

Obtenir l’autorisation directe

Une application reçoit généralement l’autorisation directe d’accéder à une ressource de deux manières :

• Via une liste de contrôle d’accès (ACL) sur la ressource
• Via l’attribution de l’autorisation d’application dans Microsoft Entra ID

Ces deux méthodes sont les plus courantes dans Microsoft Entra ID et sont recommandées pour les clients et les ressources qui exécutent le flux des informations d’identification du client. Une ressource peut également choisir d’autoriser ses clients d’autres manières. Chaque serveur de ressources peut choisir la méthode la plus logique pour son application.

Listes de contrôle d'accès

Un fournisseur de ressources peut appliquer une vérification d’autorisation basée sur une liste d’ID d’application (client) qu’il connaît et octroyer un niveau d’accès spécifique. Lorsque la ressource reçoit un jeton à partir de la plateforme d’identités Microsoft, elle peut décoder le jeton et extraire l’ID d’application du client à partir des revendications appid et iss. Elle compare ensuite l’application par rapport à une liste de contrôle d'accès qu’elle gère. La granularité et la méthode ACL peuvent varier considérablement entre les ressources.

Un cas d’utilisation typique consiste à utiliser une liste ACL afin d'exécuter des tests pour une application web ou une API Web. L’API Web peut accorder uniquement un sous-ensemble d'autorisations complètes à un client spécifique. Pour exécuter des tests de bout en bout sur l’API, vous pouvez créer un client test qui acquiert des jetons à partir de la plateforme d’identités Microsoft, puis envoie ceux-ci à l’API. L’API vérifie ensuite l’ID d’application du client de test dans la liste de contrôle d'accès pour lui accorder un accès complet à toutes les fonctionnalités de l’API. Si vous utilisez ce type de liste de contrôle d'accès, veillez à valider non seulement la valeur appid de l'appelant, mais également que la valeur iss du jeton est approuvée.

Ce type d’autorisation est courant pour les démons et les comptes de service qui doivent accéder à des données qui appartiennent à des utilisateurs avec des comptes Microsoft personnels. Pour les données appartenant à des organisations, nous vous recommandons d’acquérir l’autorisation requise via les autorisations de l’application.

Contrôle des jetons sans la revendication roles

Pour activer ce modèle d’autorisation par listes ACL, Microsoft Entra ID n’impose pas que les applications soient autorisées à obtenir des jetons pour une autre application. Les jetons de type application uniquement peuvent ainsi être émis sans revendication roles. Les applications qui exposent des API doivent implémenter des vérifications d’autorisation afin d’accepter les jetons.

Si vous souhaitez empêcher les applications d’obtenir des jetons d’accès de type application uniquement sans rôle pour votre application, veillez à ce que les exigences d’affectation soient activées pour votre application. Ainsi, les utilisateurs et les applications dépourvus de rôles ne pourront pas récupérer de jeton pour cette application.

Autorisations de l’application

Au lieu d’utiliser des listes ACL, vous pouvez utiliser des API pour exposer un ensemble d’autorisations d’application. Ceux-ci sont accordés à une application par un administrateur d’une organisation et peuvent uniquement être utilisés pour accéder aux données appartenant à cette organisation et ses employés. Par exemple, Microsoft Graph expose plusieurs autorisations d’application pour effectuer les opérations suivantes :

• Lire les messages dans toutes les boîtes aux lettres
• Lire et écrire des messages dans toutes les boîtes aux lettres
• Envoyer des messages en tant que n’importe quel utilisateur
• Lire les données du répertoire

Pour utiliser des rôles d’application (autorisations d’application) avec votre propre API (par opposition à Microsoft Graph), vous devez d’abord exposer les rôles d’application dans l’inscription de l’application de l’API dans le centre d’administration Microsoft Entra. Ensuite, configurer les rôles d’application requis en sélectionnant ces autorisations dans l’inscription de l’application de votre application cliente. Si vous n’avez pas exposé de rôles d’application dans l’inscription de l’application de votre API, vous ne pouvez pas spécifier d’autorisations d’application pour cette API dans l’inscription de l’application de votre application cliente dans le centre d’administration Microsoft Entra.

Quand vous vous authentifiez en tant qu’application (par opposition à un utilisateur), vous ne pouvez pas utiliser de permissions déléguées, car votre application n’a aucun utilisateur au nom duquel agir. Vous devez utiliser des autorisations d’application, également appelées rôles d’application, qui sont accordées par un administrateur ou le propriétaire de l’API.

Pour en savoir plus sur les autorisations d’application, consultez Autorisation et Consentement.

Recommandé : Connectez l’administrateur à votre application pour qu’il attribue des rôles d’application

En général, lorsque vous créez une application qui utilise des autorisations d’application, l’application doit disposer d’une page/vue qui permet à l’administrateur d’approuver les autorisations de l’application. Cette page peut faire partie du flux de connexion de l’application, des paramètres de l’application ou d’un flux de connexion dédié. Il est souvent judicieux pour l’application d’afficher cette vue connexion uniquement après qu’un utilisateur se soit connecté avec un compte Microsoft professionnel ou scolaire.

Si vous connectez l’utilisateur à votre application vous pouvez identifier l’organisation à laquelle l’utilisateur appartient avant de lui demander d’approuver les autorisations d’application. Bien que cela ne soit pas strictement nécessaire, cela peut vous aider à créer une expérience plus intuitive pour vos utilisateurs. Pour connecter l’utilisateur, suivez les tutoriels sur le protocole de la plateforme d’identités Microsoft.

Demander les autorisations à un administrateur d’annuaire

Lorsque vous êtes prêt à demander les autorisations à l’administrateur de l’organisation, vous pouvez rediriger l’utilisateur vers le point de terminaison de consentement administrateur de la plateforme d’identités Microsoft.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&state=12345
&redirect_uri=http://localhost/myapp/permissions

Conseil pro : Essayez de coller la requête suivante dans un navigateur.

https://login.microsoftonline.com/common/adminconsent?client_id=00001111-aaaa-2222-bbbb-3333cccc4444&state=12345&redirect_uri=http://localhost/myapp/permissions

À ce stade, Microsoft Entra ID impose que seul un administrateur de locataire puisse se connecter pour compléter la requête. L’administrateur est invité à approuver toutes les autorisations directes d’application demandées pour votre application dans le portail d’inscription des applications.

Réponse correcte

Si l’administrateur approuve les autorisations pour votre application, la réponse correcte sera :

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True

Réponse d’erreur

Si l’administrateur n’approuve pas les autorisations pour votre application, la réponse d’échec ressemble à ce qui suit :

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request

Une fois que vous avez reçu une réponse correcte du point de terminaison de mise en service de l’application, votre application a acquis les autorisations directes d’application qu’elle avait demandées. Vous pouvez désormais demander un jeton pour la ressource que vous souhaitez.

Obtention d’un jeton

Une fois que vous avez acquis l’autorisation nécessaire pour votre application, passez à l’acquisition des jetons d’accès pour les API. Pour obtenir un jeton à l’aide de l’octroi des informations d’identification du client, envoyez une demande POST à la plateforme d’identités Microsoft /token. Il existe quelques cas différents :

• Requête de jeton d’accès avec un secret partagé
• Requête de jeton d’accès avec un certificat
• Requête de jeton d’accès avec des informations d’identification fédérées

Premier cas : Requête de jeton d’accès avec un secret partagé

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

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

# Replace {tenant} with your tenant!
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'client_id=00001111-aaaa-2222-bbbb-3333cccc4444&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=A1bC2dE3f...&grant_type=client_credentials' 'https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token'

Deuxième cas : Requête de jeton d’accès avec un certificat

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

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Les paramètres pour la requête basée sur le certification ne différent que sur un point de la requête basée sur le secret partagé : le paramètre client_secret est remplacé par les paramètres client_assertion_type et client_assertion.

Troisième cas : Requête de jeton d’accès avec des informations d’identification fédérées

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

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Tous les éléments de la requête sont identiques à ceux du flux basé sur un certificat, à l’exception cruciale de la source de client_assertion. Dans ce flux, votre application ne crée pas l’assertion JWT elle-même. Au lieu de cela, votre application utilise un JWT créé par un autre fournisseur d’identité. C’est ce que l’on appelle la fédération des identités de charge de travail, où l’identité de vos applications dans une autre plateforme d’identités est utilisée pour acquérir des jetons dans la plateforme d’identités de Microsoft. Cette solution est la plus adaptée aux scénarios interclouds, comme l’hébergement de votre calcul en dehors d’Azure, mais avec un accès aux API protégées par la plateforme d’identités Microsoft. Pour des informations sur le format requis des jetons JWT créés par d’autres fournisseurs d’identité, lisez l’article sur le format d’assertion.

Réponse correcte

Une réponse correcte, quelle que soit la méthode, ressemble à ceci :

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}

Réponse d’erreur

Voici à quoi ressemble une réponse d’erreur (400 Demande incorrecte) :

{
  "error": "invalid_scope",
  "error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/.default is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "YYYY-MM-DD HH:MM:SSZ",
  "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
  "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}

Utilisation d’un jeton

Maintenant que vous avez acquis un jeton, utilisez-le pour effectuer des demandes auprès de la ressource. Lorsque le jeton expire, répétez la demande auprès du point de terminaison /token pour acquérir un nouveau jeton d’accès.

GET /v1.0/users HTTP/1.1
Host: graph.microsoft.com:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...

Essayez la commande suivante dans votre terminal, en veillant à remplacer le jeton par le vôtre.

curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG..." 'https://graph.microsoft.com/v1.0/users'

Exemples de code et autres documents

Lisez la documentation de présentation des informations d’identification du client dans la bibliothèque d’authentification Microsoft.