Documentation

Fournisseur de données

  • 1

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

    • Communiquer sur votre API : les fournisseurs de service doivent connaître vos endpoints et les scopes associés.
    • Obtenir ou implémenter un Serveur de Ressource OAuth2 qui vérifie un token auprès de FranceConnect sur notre endpoint.
    Nos Endpoints
    FranceConnect Particulier
    https://fcp.integ01.dev-franceconnect.fr/api/v1/checktoken

    FranceConnect Entreprise
    https://fce.integ01.dev-franceconnect.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 et les scopes auxquels celui-ci a droit.

    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 vérifie ensuite que les scopes de l’utilisateur sont suffisants pour accéder à la ressource demandée. Si oui, il peut en 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 n’a pas besoin d’être enregistré auprès de FC.

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

    4. Comme, pour communiquer avec le FS, le FD doit se conformer au protocole Oauth2, cela implique, entre autres, que le FD devra accepter les access_token passés par les headers et par la chaîne de query (par exemple, le FD pourra proposer un endpoint pour récupérer le nombre de points au permis de conduire sur l’URL /points_permis?token=xxxx).

    5. C’est au FD de 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>, identity_provider_host: <IDENTITY_PROVIDER_HOST>, identity_provider_id: <IDENTITY_PROVIDER_ID>, 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.

  • 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
    IDENTITY_PROVIDER_HOST Nom de domaine du fournisseur d’identité utilisé pour authentifier l’utilisateur
    IDENTITY_PROVIDER_ID Identifiant du fournisseur d’identité utilisé pour authentifier l’utilisateur
    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 du fournisseur de service