Le protocole OpenID Connect

INTRODUCTION

Le protocole OpenID Connect est au coeur du fonctionnement de FC. C'est une surcouche d'identification au protocole OAuth 2.0. Il permet à des Clients (ici, les FS) d'accéder à l'identité des Utilisateurs finaux (les internautes) par l'intermédiaire d'un serveur d'autorisation (ici, les FIs).

Les FS doivent donc être des clients OpenID Connect (aussi appelés relying parties), et les FIs doivent être des fournisseurs OpenID Connect (aussi appelés providers).

LES FLUX STANDARDS

Le protocole OpenID Connect définit 3 appels REST faits par le client, et 4 endpoints (un du côté client, et trois du côté provider).

En amont, le client s'inscrit (en général manuellement) auprès du provider. Il lui fournit une URL de callback (l'URL du client vers lequel l'internaute est redirigé une fois authentifié), aussi appelée "callback endpoint". En retour le provider donne au client un client ID et un client secret.

Lorsque l'internaute clique sur le bouton d'authentification du client, le flux est le suivant :

• Le client fait une redirection vers le "authorization endpoint" du provider avec son client id et son url de callback. Le provider redirige alors l'internaute vers sa mire d'authentification. Si l'internaute se loggue correctement, le provider renvoie un code d'autorisation au client.
• Le client fait un appel Web service vers le "token endpoint" du provider avec le code d'autorisation reçu, et authentifie cette requête avec son client id et son client secret. Le provider retourne un access token (une chaîne de caractères encodée en base64), un id token (sous la forme d'un Json Web Token, voir https://developer.atlassian.com/cloud/jira/service-desk/understanding-jwt/), et parfois un refresh token (une chaîne de caractères en base64).
• Le client fait un appel Web service vers le "userInfo endpoint" du provider avec l'access token reçu, et le provider renvoie les informations de l'internaute au client.

DANS LE CADRE DE FRANCECONNECT

Les flux FranceConnect implémentent les flux standards d'OpenID Connect. Les fournisseurs de service doivent être clients OpenID Connect, et les fournisseurs d'identité doivent être fournisseurs OpenID Connect. FranceConnect est une brique intermédiaire qui est à la fois fournisseur (du point de vue des FS) et client (du point de vue des FI).

LES DONNÉES UTILISATEUR

L'IDENTITÉ PIVOT

L'identité pivot fait partie des données usagers fournies par les Fournisseurs d'Identité aux Fournisseurs de Service, via FranceConnect . Elle permet d'identifier un utilisateur particulier.

LES DONNÉES COMPLÉMENTAIRES

Pour devenir fournisseur d'identité FranceConnect, envoyer votre demande à l'adresse support.partenaires@franceconnect.gouv.fr avec les éléments suivants :

• Nom du fournisseur d'identité
• Titre (tel qu'il apparaîtra aux utilisateurs FC)
• Email de contact
• URL du endpoint d'authentification et d'autorisation
• URL du endpoint de demande de token
• URL du endpoint de demande des informations utilisateur (identité pivot)
• URL du endpoint de logout ( norme OIDC )
• URL de endpoint de métadonnée '.well-known/openid-configuration' ( optionnel )
• Status URL (URL pour tester l'état du FI)
• Client ID
• Client secret
• Niveau eidas (eidas1 - faible, eidas2 - substantiel, eidas3 - élevé)
• Logo
• Logo focus

Nos Endpoints

En environnement d'intégration de FranceConnect, les endpoints sont disponibles en HTTPS.

FranceConnect doit être capable d'interroger le FI. Pensez à configurer votre proxy, si nécessaire, pour autoriser l'accès Internet depuis FC.

Détail du fonctionnement

Détail des flux

<FI_URL>/user/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<FC_URL>%2Foidc_callback&scope=<SCOPES>&state=<STATE>&nonce=<NONCE>&acr_values=<ACR_VALUES>

<FC_URL>/oidc_callback?code=<AUTHZ_CODE>&state=<STATE>

<FI_URL>/user/token

{
  'access_token': <ACCESS_TOKEN>,
  'token_type': 'Bearer',
  'expires_in': 3600,
  'refresh_token': <REFRESH_TOKEN>,
  'id_token': <ID_TOKEN>
}

<FI_URL>/api/user?schema=openid

<USER_INFO>

<FI_URL>/end_session_endpoint?id_token_hint=<ID_TOKEN_HINT>&post_logout_redirect_uri=<POST_LOGOUT_REDIRECT_URI>&state=<STATE>

<HTTP/1.1>404 Not Found

<HTTP/1.1>500 Internal Server Error

Utiliser les niveaux eIDAS en tant que FI

EIDAS est un nouveau standard européen visant à normaliser et à améliorer la sécurité de l'identification sur Internet. Il propose notamment 3 niveaux de garantie sur les moyens utilisés pour l'identification. En tant que FI, il est nécessaire de retourner à FranceConnect le niveau eIDAS avec lequel l'utilisateur vient de s'authentifier.

De manière analogue à ce qui est fait pour demander un FI réputé utiliser un niveau eIDAS particulier à France Connect (cf la section correspondante dans la documentation FS), le FI doit signifier à FranceConnect avec quel niveau eIDAS l'authentification s'est faite.

Dans le cadre du FI, cela se traduit par le fait de positionner le claim "acr" dans l'ID Token renvoyé au client (http://openid.net/specs/openid-connect-core-1_0.html#rfc.section.2). De la même manière que pour un FS demandant à FranceConnect de filtrer les FIs réputés compatibles avec un niveau eIDAS particulier, le claim acr retourné dans l'ID Token peut être :

• eidas1 : niveau faible (exemple : authentification par identifiant / mot de passe)
• eidas2 : niveau substantiel (exemple : second facteur. Homologué eIDAS)
• eidas3 : niveau fort (exemple : utilisation de certificats, lecteurs de cartes, ... Homologué eIDAS)

Cette donnée est retournée à FranceConnect, qui lui même la retourne au FS et au FD (sans la modifier).

En tant que FI, la gestion d'erreur est relativement simple : il faut retourner les informations d'erreur à FranceConnect (s'il y en a) par l'URL de callback fournie en utilisant le formalisme se trouvant dans la norme (exemple: http://openid.net/specs/openid-connect-core-1_0.html#AuthError).Par rapport à un FI, FranceConnect est toujours positionné en tant que client OpenID Connect, il n'est donc jamais en position de répondre quoi que ce soit à un FI.

La mire de connexion du fournisseur d'identité doit tout d'abord être responsive, afin d'être utilisable sur mobile.

Les éléments suivants y sont obligatoires, afin d'éviter l'abandon de l'usager lors d'une cinématique FranceConnect :

• Lien de contact du support du fournisseur d'identité, redirigeant vers une FAQ affichant un numéro à contacter ou un email par exemple.
• Lien de création de compte, redirigeant vers une page permettant de créer un compte chez le fournisseur d'identité.
• Lien de mot de passe oublié.

Pour une meilleure compréhension de la présence du fournisseur d'identité dans l'écosystème FranceConnect, nous recommandons également les éléments suivants sur la mire de connexion du fournisseur d'identité :

• Fond grisé avec Marianne en blanc en bas à droite.
• Logos de FranceConnect et du fournisseur d'identité.
• Lien "retourner sur FranceConnect" pour permettre le changement de fournisseur d'identité à l'usager.

Ci-dessous les éléments visuels nécessaires :

Téléchargements :

• Pack png
• Pack jpg

Il est primordial que le parcours d’identification soit communiqué à l’équipe FranceConnect le plus en amont possible de la réalisation sous la forme qui vous convient (ex: spécifications fonctionnelles ou sous forme de maquettes) à l'adresse suivante : support.partenaires@franceconnect.gouv.fr.
L’équipe FranceConnect est là pour vous aider à proposer l’expérience usager la plus adaptée. N'hésitez pas à la solliciter pour éviter d'impacter vos délais de mise en production.