Documentation

Fournisseur de données Particulier

  • 1

    Comment utiliser FranceConnect pour autoriser l'échange de données ?

    Communiquer sur votre API

    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.

    Se raccorder à FranceConnect

    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

    Endpoint
    https://app.franceconnect.gouv.fr/api/v1/checktoken

    Détail du fonctionnement

    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 :

    1. 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).

    2. 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).

    3. 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 :

    1. 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.

    2. 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.

    3. Le FD doit être capable de réconcilier l’identité pivot fournie par le FS avec sa propre base d’utilisateurs.

    4. 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 .

    5. Le FD doit vérifier que les scopes spécifiés dans l'access_token sont suffisants pour permettre d'accéder à la ressource demandée.

    DIAGRAMME DE SEQUENCE

    <pre>
                                title Vérification d'un jeton auprès de FC
    
                                FD-->FC: POST <FC_URL>/api/v1/checktoken
                                FC-->FD: HTTP Response 200
                                </pre>
                            
    Détail des flux
    <FC_URL>/api/v1/checktoken [Web Service]

    DESCRIPTION

    Contexte : Le FS a envoyé un access token au FD. Le FD veut maintenant vérifier sa validité auprès de FC. Origine : FD
    Cible : FC
    Type d’appel : WebService

    REQUETE

    URL:
    <FI_URL><FC_URL>/api/v1/checktoken
    Méthode : POST
    Corps HTTP : {‘token’ : ‘<ACCESS_TOKEN>’}

    REPONSE

    STATUS : 200
    Corps HTTP :
    {
        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


    STATUS :401

    si l’access token n’existe pas ou ne correspond pas à un utilisateur

    L'échange de données entre Fournisseur de Service et Fournisseur de Données

    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.

    Conventionnement

    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.

  • 2

    Gestion des erreurs entre le Fournisseur de Données et FranceConnect

    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"
        }
    }
  • 3

    Glossaire

    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