OpenID Connect sur la plateforme d’identité Microsoft

OpenID Connect (OIDC) étend le protocole d’autorisation OAuth 2.0 pour permettre de l’utiliser également comme protocole d’authentification supplémentaire. Vous pouvez utiliser OIDC pour activer l’authentification unique (SSO) entre vos applications OAuth à l’aide d’un jeton de sécurité appelé jeton d’ID.

La spécification complète pour OIDC est disponible sur le site web d’OpenID Foundation, à la page Spécification OpenID Connect Core 1.0.

Flux de protocole : Connexion

Ce diagramme suivant montre le flux de connexion OpenID Connect de base. Les étapes du flux sont décrites plus en détail dans les sections ultérieures de l’article.

Activer les jetons d’ID

Le jeton d’ID introduit par OpenID Connect est émis par le serveur d’autorisation, la plateforme d’identité Microsoft, lorsque l’application cliente en demande un au moment de l’authentification utilisateur. Le jeton d’ID permet à une application cliente de vérifier l’identité de l’utilisateur et d’obtenir d’autres informations (revendications) le concernant.

Les jetons d’ID ne sont pas émis par défaut pour une application inscrite auprès de la plateforme d’identité Microsoft. Les jetons d’ID d’une application sont activés à l’aide de l’une des méthodes suivantes :

1. Connectez-vous au centre d’administration Microsoft Entra.
2. Accédez à Identité>Applications>Inscriptions d’applications><Votre application>>Authentification.
3. Sous Configurations de plateformes, sélectionnez Ajouter une plateforme.
4. Dans le volet qui s’ouvre, sélectionnez la plateforme appropriée pour votre application. Par exemple, sélectionnez Web pour une application web.
5. Sous URI de redirection, ajoutez l’URI de redirection de votre application. Par exemple : https://localhost:8080/.
6. Sous Flux d’octroi implicite et flux hybride, cochez la case Jetons d’ID (utilisés pour les flux implicites et hybrides).

Ou :

1. Sélectionnez Identité>Applications>Inscriptions d’applications><votre application>>Manifeste.
2. Définissez oauth2AllowIdTokenImplicitFlow sur true dans le manifeste d’application de l’inscription de l’application.

Si les jetons d’ID ne sont pas activés pour votre application et qu’un jeton est demandé, la plateforme d’identités Microsoft renvoie une erreur unsupported_response semblable à :

La valeur fournie pour le paramètre d’entrée 'response_type' n’est pas autorisée pour ce client. La valeur attendue est « code ».

La demande d’un jeton d’ID en spécifiant id_token comme response_type est expliquée dans la section Envoyer la requête de connexion, plus loin dans l’article.

Récupérer le document de configuration OpenID

Les fournisseurs OpenID comme la plateforme d’identité Microsoft fournissent un document de configuration de fournisseur OpenID sur un point de terminaison accessible publiquement, contenant les points de terminaison OIDC, les revendications prises en charge et d’autres métadonnées du fournisseur. Les applications clientes peuvent utiliser les métadonnées pour découvrir les URL à utiliser pour l’authentification et les clés de signature publiques du service d’authentification.

Les bibliothèques d’authentification sont les consommateurs les plus courants du document de configuration OpenID, qu’elles utilisent pour la découverte des URL d’authentification, des clés de signature publiques du fournisseur et d’autres métadonnées du service. Si une bibliothèque d’authentification est utilisée dans votre application, vous n’aurez probablement pas besoin de coder manuellement des requêtes et réponses à partir du point de terminaison du document de configuration OpenID.

Rechercher l’URI du document de configuration OpenID de votre application

À chaque inscription d’application dans Microsoft Entra ID est fourni un point de terminaison qui est accessible publiquement et sert de document de configuration OpenID. Pour déterminer l’URI du point de terminaison du document de configuration pour votre application, ajoutez le chemin de la configuration OpenID connue à l’URL de l’autorité de votre inscription d’application.

• Chemin du document de la configuration connue : /.well-known/openid-configuration
• URL de l'autorité : https://login.microsoftonline.com/{tenant}/v2.0

La valeur de {tenant} varie en fonction de l’audience de connexion de l’application, comme indiqué dans le tableau suivant. L’URL de l’autorité dépend aussi de l’instance cloud.

Pour trouver le document de configuration OIDC dans le centre d’administration Microsoft Entra, connectez-vous au centre d’administration Microsoft Entra, et ensuite :

1. Accédez à Identité>Applications>Inscriptions d’applications><Votre application>>Points de terminaison.
2. Recherchez l’URI sous Document de métadonnées OpenID Connect.

Exemple de requête

La requête suivante obtient les métadonnées de configuration OpenID à partir du point de terminaison du document de configuration OpenID de l’autorité common sur le cloud public Azure :

GET /common/v2.0/.well-known/openid-configuration
Host: login.microsoftonline.com

Exemple de réponse

Les métadonnées de configuration sont retournées au format JSON, comme illustré dans l’exemple suivant (tronqué par souci de concision). Les métadonnées retournées dans la réponse JSON sont décrites en détail dans la spécification de découverte OpenID Connect 1.0.

{
  "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize",
  "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "private_key_jwt"
  ],
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys",
  "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
  "subject_types_supported": [
      "pairwise"
  ],
  ...
}

Envoyer la requête de connexion

Pour authentifier un utilisateur et demander un jeton d’ID à utiliser dans votre application, redirigez sa requête user-agent vers le point de terminaison /authorize de la plateforme d’identité Microsoft. La requête est similaire au premier tronçon du flux de code d’autorisation OAuth 2.0, avec toutefois ces distinctions :

• Incluez l’étendue openid dans le paramètre scope.
• Spécifiez id_token dans le paramètre response_type.
• Incluez le paramètre nonce.

Exemple de requête de connexion (sauts de ligne inclus uniquement pour une meilleure lisibilité) :

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=form_post
&scope=openid
&state=12345
&nonce=678910

À ce stade, l’utilisateur est invité à saisir ses informations d’identification et à exécuter l’authentification. La plateforme d’identités Microsoft vérifie que l’utilisateur a accepté les autorisations indiquées dans le paramètre de requête scope. Si l’utilisateur n’a pas accepté l’une ou plusieurs de ces autorisations, la plateforme d’identités Microsoft lui demande de corriger ce manquement. Vous pouvez en savoir plus sur les autorisations consentements et applications mutualisées.

Une fois que l’utilisateur a procédé à l’authentification et accordé son consentement, la plateforme d’identités Microsoft renvoie une réponse à votre application à l’URI de redirection indiqué, à l’aide de la méthode spécifiée dans le paramètre response_mode.

Réponse correcte

Une réponse réussie lorsque vous utilisez response_mode=form_post ressemble à ceci :

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Réponse d’erreur

Les réponses d’erreur peuvent également être envoyées à l'URI de redirection afin que l’application puisse les traiter. Par exemple :

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Codes d’erreur pour les erreurs de point de terminaison d’autorisation

Le tableau suivant décrit les codes d’erreur qui peuvent être retournés dans le paramètre error de la réponse d’erreur :

Validation du jeton d’ID

La réception d’un jeton d’ID dans votre application peut ne pas toujours être suffisante pour authentifier entièrement l’utilisateur. Vous pouvez également avoir besoin de valider la signature du jeton d’ID et de vérifier ses revendications par rapport aux exigences de votre application. Comme tous les fournisseurs OpenID, les jetons d’ID de la plateforme d’identité Microsoft sont des jetons web JSON (JWT) signés par la méthode de cryptographie à clé publique.

Les applications web et les API web qui utilisent des jetons d’ID pour l’autorisation doivent les valider, car ces applications contrôlent l’accès aux données. Toutefois, d’autres types d’applications n’utilisent pas la validation de jeton d’ID. Les applications natives et monopages (SPA), par exemple, utilisent rarement la validation de jeton d’ID, car tout entité disposant d’un accès physique à l’appareil ou au navigateur peut potentiellement contourner la validation.

Voici deux exemples de contournement de la validation des jetons :

• Fourniture de jetons ou clés fictifs en redirigeant le trafic réseau vers l’appareil
• Débogage de l’application et exécution pas à pas de la logique de validation pendant l’exécution du programme.

Si vous validez les jetons d’ID dans votre application, nous vous recommandons de ne pas le faire manuellement. À la place, utilisez une bibliothèque de validation des jetons pour analyser et valider des jetons. Les bibliothèques de validation des jetons sont disponibles pour la plupart des langages, frameworks et plateformes de développement.

Informations à valider dans un jeton d’ID

En plus de valider la signature du jeton d’ID, vous devez valider plusieurs de ses revendications, comme cela est expliqué dans Validation d’un jeton d’ID. Consultez également Informations importantes sur la substitution des clés de signature.

Plusieurs autres validations sont fréquemment demandées et varient selon le scénario d’application :

• S’assurer que l’utilisateur/l’organisation s’est inscrit pour l’application.
• S’assurer que l’utilisateur dispose de l’autorisation/des privilèges appropriés.
• S’assurer de l’utilisation d’une force certaine d’authentification, comme une authentification multifacteur.

Une fois que vous avez validé le jeton d’ID, vous pouvez commencer une session avec l’utilisateur et utiliser les informations contenues dans les revendications du jeton pour la personnalisation de l’application, son affichage ou le stockage de ses données.

Schéma de protocole : Acquisition de jeton d'accès

Beaucoup d’applications doivent non seulement connecter un utilisateur, mais également accéder à une ressource protégée comme une API web pour le compte de l’utilisateur. Ce scénario utilise à la fois OpenID Connect, pour obtenir un jeton d’ID pour authentifier l’utilisateur, et OAuth 2.0 afin d’obtenir un jeton d’accès pour une ressource protégée.

Le flux complet de connexion OpenID Connect et d’acquisition des jetons ressemble à ce diagramme :

Obtenir un jeton d’accès pour le point de terminaison UserInfo

En plus du jeton d’ID, les informations de l’utilisateur authentifié sont également mises à disposition sur le point de terminaison UserInfo OIDC.

Pour obtenir un jeton d’accès pour le point de terminaison UserInfo OIDC, modifiez la requête de connexion comme ceci :

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444        // Your app registration's Application (client) ID
&response_type=id_token%20token                       // Requests both an ID token and access token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F       // Your application's redirect URI (URL-encoded)
&response_mode=form_post                              // 'form_post' or 'fragment'
&scope=openid+profile+email                           // 'openid' is required; 'profile' and 'email' provide information in the UserInfo endpoint as they do in an ID token. 
&state=12345                                          // Any value - provided by your app
&nonce=678910                                         // Any value - provided by your app

Vous pouvez utiliser le flux de code d’autorisation, le flux de code de l’appareil ou un jeton d’actualisation à la place de response_type=token pour obtenir un jeton d’accès pour votre application.

Réponse de jeton correcte

Réponse correcte après l’utilisation de response_mode=form_post :

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded
 access_token=eyJ0eXAiOiJKV1QiLCJub25jZSI6I....
 &token_type=Bearer
 &expires_in=3598
 &scope=email+openid+profile
 &id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI....
 &state=12345

Les paramètres de la réponse signifient la même chose quel que soit le flux utilisé pour les acquérir.

Réponse d’erreur

Les réponses d’erreur peuvent également être envoyées à l'URI de redirection afin que l’application puisse les traiter de manière appropriée :

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Pour obtenir une description des codes d’erreur éventuels et connaître les réponses client recommandées associées, consultez Codes d’erreur pour les erreurs de point de terminaison d’autorisation.

Une fois que vous avez obtenu un code d'autorisation et un jeton d'ID, vous pouvez connecter l’utilisateur et obtenir des jetons d’accès pour son compte. Pour connecter l’utilisateur, vous devez valider le jeton d’ID comme décrit dans les jetons de validation. Pour obtenir des jetons d’accès, suivez la procédure décrite dans la documentation du flux de code OAuth.

Appel du point de terminaison UserInfo

Consultez la documentation relative à UserInfo pour savoir comment appeler le point de terminaison UserInfo avec ce jeton.

Envoi d’une demande de déconnexion

Pour déconnecter un(e) utilisateur(-trice), effectuez les deux opérations suivantes :

1. Rediriger la requête user-agent de l’utilisateur vers l’URI de déconnexion de la plateforme d’identité Microsoft.
2. Effacez les cookies de votre application ou mettez fin à la session de l’utilisateur(-trice) dans votre application.

Si vous ne parvenez pas à effectuer l’une ou l’autre de ces opérations, l’utilisateur peut rester authentifié et ne pas être invité à se connecter à la prochaine utilisation de votre application.

Redirigez la requête user-agent vers end_session_endpoint comme cela est décrit dans le document de configuration OpenID Connect. end_session_endpoint prend en charge les requêtes HTTP GET et POST.

GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Déconnexion unique

Lorsque vous redirigez l’utilisateur vers l’application end_session_endpoint, la plateforme d’identités Microsoft met fin à la session de l’utilisateur pour cette application. Toutefois, l’utilisateur peut rester connecté à d’autres applications qui utilisent les mêmes comptes Microsoft pour l’authentification.

Lorsqu’un utilisateur est connecté à plusieurs applications web ou SPA inscrites dans ce répertoire (également appelé locataire), la déconnexion unique lui permet de se déconnecter instantanément de toutes les applications en se déconnectant dans une seule d’entre elles.

Pour activer la déconnexion unique pour votre application Entra, vous devez utiliser la fonctionnalité de déconnexion du canal frontal OpenID Connect. Cette fonctionnalité permet à une application de notifier d’autres applications que l’utilisateur s’est déconnecté. Lorsque l’utilisateur se déconnecte d’une application, lea plateforme d’identités Microsoft envoie une requête HTTP GET à l’URL de déconnexion du canal frontal de chaque application à laquelle l’utilisateur est actuellement connecté.

Ces applications doivent répondre à cette requête en effectuant les deux actions suivantes pour que la déconnexion unique réussisse :

1. Supprimer toute session qui identifie l’utilisateur.
2. Les applications doivent répondre à cette requête en effaçant toute session qui identifie l’utilisateur et en renvoyant une réponse 200.

Qu’est-ce qu’une URL de déconnexion du canal frontal ?

L’URL de déconnexion du canal frontal est l’endroit où votre application web ou SPA reçoit la demande de déconnexion du serveur d’authentification Entra et exécute la fonctionnalité de déconnexion unique. Chaque application a une URL de déconnexion de canal frontal.

Quand devez-vous définir une URL de déconnexion de canal frontal ?

Si vous ou votre développeur avez déterminé que la déconnexion unique est requise pour une application, vous devez définir l’URL de déconnexion du canal frontal pour l’inscription de cette application. Une fois que l’URL de déconnexion du canal frontal est définie pour l’inscription de cette application, la plateforme d’identités Microsoft envoie une requête HTTP GET à l’URL de déconnexion du canal frontal de cette application lorsque l’utilisateur qui y est connecté se déconnecte d’une autre application.

Comment configurer la déconnexion unique à l’aide de la fonctionnalité de déconnexion du canal frontal

Pour utiliser la fonctionnalité de déconnexion du canal frontal pour un ensemble d’applications, vous devez effectuer les deux tâches suivantes :

• Définissez l’URL de déconnexion du canal frontal dans le Centre d’administration Microsoft Entra pour toutes les applications qui doivent être déconnectées simultanément. Chaque application a généralement sa propre URL de déconnexion du canal frontal dédiée.
• Modifiez le code des applications afin qu’elles écoutent une requête HTTP GET envoyée par la plateforme d’identités Microsoft à l’URL de déconnexion du canal frontal et qu’elles répondent à cette requête en supprimant toute session qui identifie l’utilisateur et en renvoyant un code de réponse 200.

Comment choisir une URL de déconnexion du canal frontal

L’URL de déconnexion du canal frontal doit être une URL capable de recevoir et de répondre aux requêtes HTTP GET et doit pouvoir supprimer toute session qui identifie l’utilisateur. Voici des exemples, parmi d’autres, d’URL de déconnexion du canal frontal :

• https://example.com/frontchannel_loout
• https://example.com/signout
• https://example.com/logout

Étapes suivantes

• Consultez la documentation sur les points de terminaison UserInfo.
• Remplissez les valeurs des revendications dans un jeton avec des données des systèmes locaux.
• Incluez vos propres revendications dans les jetons.