Fournisseur de données Particulier
Auprès des futurs clients :
Les fournisseurs de service doivent connaître vos endpoints et les scopes associés.
Pour ce faire, vous devez référencer votre API dans le catalogue api.gouv.fr en joignant une description fonctionnelle de l'api ainsi que sa documentation technique, par exemple au format openAPI.
Auprès de FranceConnect :
Pour afficher un libellé explicite dans la page de consentement à l'usager, FranceConnect doit connaitre, pour chacun de vos scopes, le libellé qu’il affichera à l’usager dans la page de consentement.
Pour ce faire, vous devez communiquer à FranceConnect chaque couple { scope + libellé correspondant } que vous avez configuré sur votre Fournisseur de Données.
Utiliser FC pour l’échange de données consiste notamment à recevoir un access_token de la part du Fournisseur de Service et à valider cet access_token auprès de FranceConnect pour recevoir l’Identité Pivot.
Cette validation s’effectue en appelant le endpoint de FranceConnect Particulier indiqué ci-dessous.
Pour cela, vous devez obtenir ou implémenter un serveur de ressource OAuth2. FranceConnect se comporte alors comme un Serveur d’Autorisation OAuth2.
Nous mettons à disposition des exemples de fournisseurs de données à cette adresse : https://github.com/france-connect/data-providers-examples
https://app.franceconnect.gouv.fr/api/v1/checktoken |
CINEMATIQUE
Le FD doit implémenter le protocole OAuth2 en tant que Fournisseur de Ressource, et voit FC comme le Serveur d’Autorisation.
La cinématique est la suivante :
Le FS contacte le FD pour lui demander des informations. Conformément au protocole OAuth2, ce FS envoie dans la requête un access token (qui lui a été donné par FranceConnect pour un ou plusieurs scopes).
Une fois la demande reçue, le FD doit s’assurer de la validité de l’access token. Pour cela, il interroge FranceConnect. FranceConnect renvoie une erreur 400 ou 401 si cet access token n’est pas valide/connu. S’il est valide, FranceConnect renvoie l’identité pivot de l’utilisateur, l’identifiant du Fournisseur de Service et les scopes auxquels le FS a droit (par contractualisation avec le FD).
Le FD doit réconcilier l’identité pivot avec sa propre base d’utilisateurs. S’il parvient à réconcilier l’identité pivot avec un utilisateur, il peut renvoyer la ressource au FS.
Quelques règles complémentaires à suivre :
Le FD est “maître à bord” sur ce qu’il expose, à qui, et comment. La seule contrainte technique est l’utilisation du protocole OAuth2 pour communiquer avec FS et FC.
Le FD doit se faire connaitre auprès de FC. Il doit notamment communiquer les couples { scope + libellé correspondant } pour l'affichage dans la fenêtre d'information/consentement affichée à l'usager par FC.
Le FD doit être capable de réconcilier l’identité pivot fournie par le FS avec sa propre base d’utilisateurs.
Pour communiquer avec le FS, le FD doit se conformer au protocole OAuth2. Par exemple, le FS peut envoyer l'access_token soit dans les headers soit dans la chaîne de query ; le FD doit donc accepter les deux modes de transmission. Par exemple, pour le mode query, le FD pourrait proposer un endpoint pour récupérer le nombre de points de permis de conduire sur le endpoint /point_permis?token=xxx .
DIAGRAMME DE SEQUENCE
DESCRIPTION
Contexte : Le FS a envoyé un access token au FD. Le FD veut maintenant vérifier sa validité auprès de FC. Origine : FDREQUETE
URL:<FI_URL><FC_URL>/api/v1/checktokenMéthode : POST
REPONSE
STATUS : 200{ identity: <ID_PIVOT>, scope: <SCOPES>, client: <CLIENT>, acr: <NIVEAU EIDAS> }STATUS :400
si une erreur est survenue lors de la recherche de l’access token
si l’access token n’existe pas ou ne correspond pas à un utilisateur
Aujourd'hui, l'échange de données se fait en mode "ad hoc" entre Fournisseur de Services et Fournisseur de Données. Dans cet échange, FranceConnect tient un rôle de "tiers de confiance". Il va fournir des jetons d'accès au Fournisseur de Services pour les scopes convenus avec les FDs avec lesquels il échange. Le jeton contenant les scopes est transmis au FS suite au consentement de l'usager.
Lors de l'authentification il est également possible d'ajouter dans les scopes n'importe quel scope dans la liste. Cela permet de faire une seule demande d'autorisation pour l'ensemble des scopes souhaités. Le FS peut ainsi utiliser le même access_token pour échanger avec plusieurs FD.
Préalablement à la mise en place de l'échange "ad hoc" technique, FranceConnect propose également un outil qui permet aux FS et aux FD de faciliter leur mise en relation, signup.api.gouv.fr. Les 2 parties peuvent s'accorder sur chacune des modalités de la consommation de l'API : prérequis et conditions juridiques, organisationnelles, fonctionnelles et techniques.
De plus, la validité de la convention peut être vérifiée à chaque échange entre le FS et le FD grâce au mécanisme OAuth2.
FranceConnect traite les cas suivants :
Code HTTP | Name | Message | Explications |
---|---|---|---|
400 | invalid_request | The request does not contain an access token | La requête du FD est incomplète : elle devrait contenir un access token. |
401 | invalid_token | The access token is wrongly formatted | Le token fourni par le FD est mal formé. |
401 | invalid_token | Access token not found | Le token fourni par le FD n'a pas été retrouvé par FranceConnect, la requête ne peutpas être traitée. |
401 | invalid_token | Token matches no user | Le token est valide et existe côté FranceConnect, mais FranceConnect n'est pas en mesure de fournir l'identité pivot associée. |
500 | server_error | Internal Server Error | Une erreur technique imprévue est survenue côté FranceConnect. |
FranceConnect renvoie ces messages d’erreurs au format JSON en suivant le formalisme suivant :
{ "error": { "name":"<nom de l'erreur>", "message":"<message donnant des détails sur l'erreur>" } }
Exemple : Dans le cas ou la requête au service /checktoken ne contiendrait pas d’access_token, le service renverra le message suivant (avec un code retour HTTP = 400) :
{ "error": { "name":"invalid_request", "message":"The request does not contain an access token" } }
FC_URL | URL de FranceConnect |
---|---|
CLIENT | L’identifiant et le libellé du Fournisseur de service qui a fait la demande, au format suivant : {client_id: ‘123456’, client_name: ‘Mairie_De_Paris’} |
ACCESS_TOKEN | Token généré par FC, envoyé par le FS au FD |
NIVEAU_EIDAS | Même niveau que celui retourné dans le champ “acr” de l’id_token lors d’une cinématique d’authentification. C’est le niveau eidas qui a été utilisé par l’utilisateur pour se connecter et générer le jeton en cours de vérification |
SCOPES | La liste de scopes pour lesquels l’utilisateur a demandé l’autorisation. Si l’utilisateur demande une ressource et ne possède pas le(s) scope(s) nécessaires pour cette ressource, le FD ne doit pas donner accès à la ressource. |
ID_PIVOT | Voir la section identité pivot de la documentation liée au fournisseur de service |