Le protocole OpenID Connect

INTRODUCTION

Le protocole OpenID Connect est au cœur 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) et un id token (sous la forme d'un Json Web Token).
• 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 usagers

Les données usagers sont fournies par les Fournisseurs d'Identité aux Fournisseurs de Service, via FranceConnect Particuliers, conformément à l'habilitation obtenue.

Afin d'implémenter FranceConnect, il vous faut obtenir une habilitation pour votre démarche sur la plateforme : https://franceconnect.gouv.fr/partenaires.
Une fois votre cas d'usage validé, vous recevrez une invitation pour accéder au Portail Partenaire et commencer vos tests d'intégration.

Sur notre environnement d'intégration, vous pouvez utiliser le fournisseur d'identité "Démonstration" dont les données sont modifiables ici : https://github.com/france-connect/identity-provider-example/blob/master/database.csv

Vous pouvez proposer de nouvelles identités de tests directement sur ce fichier.

Nos Endpoints

Intégration

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

Production

Détail du fonctionnement

La récupération de l'identité pivot doit être faite dans la suite immédiate des appels précédents (authentification et récupération du code). Le fait d'appeler ce Web service plus tard n'est aujourd'hui pas proposé.

Détail des flux

<FC_URL>/api/v1/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<FS_URL>%2F<URL_CALLBACK>&scope=<SCOPES>&state=><STATE>&nonce=<NONCE>

<FS_URL>/<URL_CALLBACK>?code=<AUTHZ_CODE>&state=<STATE>

<FC_URL>/api/v1/token

{
  'access_token': <ACCESS_TOKEN>,
  'token_type': 'Bearer',
  'expires_in': 60,
  'id_token': <ID_TOKEN>
}

<FC_URL>/api/v1/userinfo?schema=openid

<USER_INFO>

Données usager

LISTE DES SCOPES DISPONIBLES LORS DE L'ÉTAPE D'AUTHENTIFICATION FRANCECONNECT

FranceConnect a étendu le mécanisme de scopes pour qu'il soit plus modulaire.

• Un seul scope est obligatoire : openid. Il permet de récupérer le sub (identifiant unique technique) de l'utilisateur.
• Il est possible de récupérer individuellement chaque propriété de l'identité pivot en utilisant leurs scopes dédiés
• Il est possible de combiner plusieurs scopes de son choix pour récupérer seulement les informations dont a besoin le FS

Cette liste de scopes est définie par la norme OpenIDConnect : http://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims

Intégration d'un bouton FranceConnect

Les boutons d’action FranceConnect sont primordiaux dans l’usage du service. Il est obligatoire d’utiliser l’un des boutons proposé et aucun autre visuel pour la connexion des usagers.

Pour les boutons en svg, lors de l'utilisation d'une image veuillez preciser la taille du bouton.

Téléchargements :

• Pack boutons

Utiliser les niveaux eIDAS en tant que FS

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. Vous pouvez, en tant que FS, utiliser les niveaux eIDAS pour que FC filtre les FIs réputés compatibles avec un niveau eIDAS précis.

Comme la norme ne prévoit pas aujourd'hui de mesures techniques particulières pour préciser le niveau souhaité, FranceConnect utilise le claim optionnel "acr" (http://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters) de la norme OpenID Connect. Pour le FS, cela veut dire remplir le claim optionnel acr_values lors de la demande d'authentification (appel à l'endpoint /api/v1/authorize).

Au sujet du claim acr_values, on notera que c'est, selon la norme, un "voluntary claim" qui théoriquement traduit une préférence et non une exigence. Le fait de fournir ce claim va faire filtrer à FranceConnect les FIs réputés répondre à la demande qui est faite et le FI renverra, par le biais de FranceConnect le niveau eIDAS avec lequel l'authentification a eu lieu. Le FS pourra donc vérifier le niveau eIDAS utilisé.

Exemple d'appel précisant un niveau eIDAS minimum :

https://fcp.integ01.dev-franceconnect.fr/api/v1/authorize?response_type=code&client_id=123456&redirect_uri=https%3A%2F%2Ffournisseur-de-service.dev-franceconnect.fr%2Flogin-callback&scope=openid%20profile%20email%20address%20phone%20preferred_username%20email%20address%20phone%20preferred_username&acr_values=eidas1&state=randomValue&nonce=randomValue

Afin d'y arriver, il faut spécifier une ou plusieurs valeurs parmi les suivantes :

• eidas1 : niveau standard (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)

Si le claim acr n'est pas précisé, le niveau par défaut est fixé à eidas3, le plus sécurisé.
Si le claim est précisé, FranceConnect ne proposera à l'utilisateur que les fournisseurs d'identité de niveau supérieur ou égal. Sinon, FranceConnect ne proposera à l'utilisateur que les Fournisseurs d'Identité de niveau élevé.
Si plusieurs niveaux sont précisés, FranceConnect considère que le claim n'est pas valide.
Si le claim est considéré par FranceConnect comme n'étant pas valide, le niveau par défaut est utilisé.

Le niveau eIDAS utilisé pour l'authentification est retourné par le fournisseur d'identité (cf la documentation du FI), par le biais de FranceConnect (qui le transmet sans le modifier) et du claim acr dans l'ID Token retourné au Fournisseur de Service.
Il est de la responsabilité du Fournisseur de service de s'assurer que le niveau retourné est au moins égal ou supérieur à celui demandé (si eidas2 est demandé, eidas3 doit être accepté tout comme eidas2, mais pas eidas1).

FranceConnect implémente la section sur la déconnexion en cours de spécification dans la norme OpenID Connect :http://openid.net/specs/openid-connect-session-1_0.html#RPLogout

FranceConnect ne gère pas la déconnexion de l'usager au service FranceConnect à la fermeture du navigateur.

Le FS doit pouvoir déconnecter l'utilisateur de sa session FranceConnect. La cinématique globale est celle-ci :

• L' utilisateur clique sur un lien de déconnexion présenté par le FS.
• Le FS doit déconnecter l'utilisateur de son application et de sa session FranceConnect.
• L' utilisateur est redirigé vers la page de retour spécifiée par le FS.

Le FS doit préciser l'URL où l'on doit rediriger l'utilisateur une fois qu'il a choisi de se déconnecter ou non de FranceConnect via le paramètre post_logout_redirect_uri, ainsi que passer l'id_token récupéré lors de l'authentification de l'utilisateur via le paramètre id_token_hint.

Il est obligatoire de renseigner les différentes urls de redirections de déconnexion dans les paramètres client

<FC_URL>/api/v1/logout?id_token_hint=<ID_TOKEN_HINT>&state=<STATE>&post_logout_redirect_uri=<POST_LOGOUT_REDIRECT_URI>

Un fournisseur de service de démo est mis à votre disposition sur https://fournisseur-de-service.dev-franceconnect.fr

Celui propose également d'appeler un fournisseur de données "FranceConnecté", simulant actuellement un échange de données avec la DGFIP.

Tous les liens importants (documentation, code source, etc) sont dans le footer du site d'exemple.

Détail du fonctionnement

Vous devez pouvoir à la fois communiquer avec FranceConnect et avec le FD de votre choix. Il faut donc veiller à ce que les flux entre les machines ne soient pas bloqués (pour FC, les ports 80 et 443).

Détail des flux

<FS_URL>/<url-demarche>

<FC_URL>/api/v1/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<FS_URL>%2F<CALLBACK_URL_DATA>&scope=<SCOPES>&state=<STATE>&nonce=<NONCE>

<FC_URL>/consent?return_url=%2Fuser%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D<CLIENT_ID>%26scope%3D<SCOPES>%26redirect_uri%3D<CALLBACK_URL_DATA>

<FC_URL>/consent?return_url=%2Fuser%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D<CLIENT_ID>%26scope%3D<SCOPES>%26redirect_uri%3D<CALLBACK_URL_DATA>

<CALLBACK_URL_DATA>?code=<AUTHZ_CODE>"&state=<STATE>

<FC_URL>/api/v1/token

{
  'access_token': <ACCESS_TOKEN>,
  'token_type': 'Bearer',
  'expires_in': 60,
  'id_token': <ID_TOKEN>
}

<FD_URL>/<DATA_ENDPOINT>

En tant qu'OpenID Connect provider, FranceConnect peut renvoyer toutes sortes d'erreurs à une application cliente. Pour se faire, FranceConnect passe par le mécanisme de retour d'erreurs d'un fournisseur d'identité openid connect tel que décrit dans la norme ( http://openid.net/specs/openid-connect-core-1_0.html#AuthError, en particulier les sections 3.1.2.6 (authentification), 3.1.3.4 (jeton d'accès), 5.3.3 (service d'informations utilisateur) )

Afin de rendre plus simple la détection et la gestion de bugs, FranceConnect possède un système de codes d'erreurs.

FranceConnect gère plusieurs types de données "périssables" lors du déroulé d'une authentification par OpenID Connect ou de la fourniture d'un jeton d'accès à une ressource protégée (cinématique OAuth2 classique). Chacune de ces données possède une durée de vie qui lui est propre au delà de laquelle elle doit être régénérée. En voici le détail :

Ci-dessous les éléments permettant une recette technique. En ce qui concerne la recette fonctionnelle, l'équipe FranceConnect a mis en place une démarche pour demander la qualification de votre service. Nous vous prions de bien vouloir y déposer votre demande afin qu'elle puisse être étudiée et traitée. Cette démarche est disponible à l'adresse suivante : https://www.demarches-simplifiees.fr/commencer/demande-qualification-fs