Documentation

Fournisseur de service

  • 1

    Concepts de base

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

    La spécification du protocole se trouve sur http://openid.net/connect/.

    Pour une référence d'implémentation OpenID Connect voici le lien : http://openid.net/specs/openid-connect-core-1_0.html

    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/static/connect/docs/concepts/understanding-jwt.html), 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).

    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 ou une entreprise.

    FranceConnect Particulier
    Champs Type Description
    given_name string prénoms séparés par des espaces (standard OpenIDConnect)
    family_name string le nom de famille de naissance (standard OpenIDConnect)
    birthdate string la date de naissance au format YYYY-MM-DD (standard OpenIDConnect)
    gender string male pour les hommes, female pour les femmes (standard OpenIDConnect)
    birthplace string le code INSEE du lieu de naissance (ou une chaîne vide si la personne est née à l'étranger)
    birthcountry string le code INSEE du pays de naissance

    FranceConnect Entreprise
    Champs Type Description
    given_name string prénoms séparés par des espaces (standard OpenIDConnect)
    family_name string le nom de famille (standard OpenIDConnect)
    email string l'adresse mail de la personne
    siret string le numéro SIRET ou SIREN de l'entreprise (non standard)

  • 2

    Je veux identifier/authentifier des utilisateurs via FC

    • Vous inscrire via ce formulaire : nous vous enverrons alors un client ID et un client secret.
    • Obtenir un client OpenId Connect
    • Configurer dans votre client OpenID Connect nos endpoints, votre URL de callback, le client ID et le client secret.
    • Insérer dans votre site un bouton FC qui pointe vers votre URL qui déclenche la première étape de la cinématique OpenID Connect. Vous pouvez retrouvez ici les ressources graphiques
    Nos Endpoints

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

    FranceConnect Particulier
    Authorization https://fcp.integ01.dev-franceconnect.fr/api/v1/authorize
    Token https://fcp.integ01.dev-franceconnect.fr/api/v1/token
    UserInfo https://fcp.integ01.dev-franceconnect.fr/api/v1/userinfo
    Logout https://fcp.integ01.dev-franceconnect.fr/api/v1/logout

    FranceConnect Entreprise
    Authorization https://fce.integ01.dev-franceconnect.fr/api/v1/authorize
    Token https://fce.integ01.dev-franceconnect.fr/api/v1/token
    UserInfo https://fce.integ01.dev-franceconnect.fr/api/v1/userinfo
    Logout https://fce.integ01.dev-franceconnect.fr/api/v1/logout
    Détail du fonctionnement
                            title Séquence d'authentification (Fournisseur de service)
    
                            note right of Utilisateur
                                L'utilisateur clique sur
                                le bouton "FranceConnect"
                            end note
    
                            Utilisateur->FS:
                            FS-->Utilisateur: Redirect 302 <FC_URL>/api/v1/authorize
    
                            Utilisateur->FC: GET <FC_URL>/api/v1/authorize
    
                            FC-->Utilisateur: Redirect 302 <FS_URL>/<URL_CALLBACK>
    
                            Utilisateur->FS: GET <FS_URL>/<URL_CALLBACK>
    
                            FS->FC: POST <FC_URL>/api/v1/token
    
                            FC->FS: HTTP Response 200
    
                            FS->FC: GET <FC_URL>/api/v1/userinfo
    
                            FC->FS: HTTP Response 200
    
                            FS-->Utilisateur: Redirect 302 <FS_URL>/page_authentifiée
    
                            note right of Utilisateur
                                Plus tard, l'utilisateur se déconnecte
                            end note
    
                            Utilisateur->FS:
    
                            FS-->Utilisateur: Redirect 302 <FC_URL>/api/v1/logout
    
                            Utilisateur->FC: GET <FC_URL>/api/v1/logout
    
                            FC->Utilisateur: Redirect 302 <FC_URL>/<POST_LOGOUT_REDIRECT_URI
    
                            Utilisateur->FS: GET <FC_URL>/<POST_LOGOUT_REDIRECT_URI
                          

    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 [Redirection]

    DESCRIPTION

    Contexte : Le FS redirige depuis la requête précédente vers /api/v1/authorize pour engager la cinématique d'authentification.
    Origine : FS
    Cible : FC
    Type d'appel : redirection navigateur

    Note : il est possible d'ajouter des paramètres supplémentaires dynamiques via la redirect_uri, à passer après ? sous la forme clé=valeur. Ils seront renvoyés tels quels lors du retour vers le FS.
    Exemple :
    si vous redirigez vers l'URL https://fcp.integ01.dev-franceconnect.fr/api/v1/authorize?response_type=[...]&client_id=[...]&redirect_uri=https%3A%2F%2Ffs.fr%2Foidc_callback%3Ftestkey%3Dtestvalue&state=[...]&nonce=[...]&scope=[...]
    alors FC redirigera vers le FS à l'URL https://fs.fr/oidc_callback?testkey=testvalue&[...]
    Cela permet de conserver un état quand le site de départ et le site d'arrivée ne partagent pas leurs sessions Web.

    REQUETE

    URL:

    <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>
    Méthode : GET


    REPONSE

    /

    <FS_URL>/<URL_CALLBACK> [Redirection]

    DESCRIPTION

    Contexte : L'internaute s'est identifié sur le FI, FranceConnect redirige vers le callback du FS, avec un Authorization code dans l'URL.
    Origine : FC
    Cible : FS
    Type d'appel : redirection navigateur


    REQUETE

    URL:
    <FS_URL>/<URL_CALLBACK>?code=<AUTHZ_CODE>&state=<STATE>
    Méthode : GET
    <FC_URL>/api/v1/token [Web Service]

    DESCRIPTION

    Contexte : Le FS a récupéré un authorization code. Il veut maintenant récupérer un access token et un id token.
    Origine : FS
    Cible : FC
    Type d'appel : appel de Web service


    REQUETE

    URL:
    <FC_URL>/api/v1/token
    Méthode : POST
    Corps HTTP :
    • 'grant_type': 'authorization_code',
    • 'redirect_uri': '<FS_URL>/<URL_CALLBACK>',
    • 'client_id': '<CLIENT_ID>',
    • 'client_secret': '<CLIENT_SECRET>',
    • 'code': '<AUTHZ_CODE>'

    REPONSE

    Corps HTTP:

    {'access_token': <ACCESS_TOKEN>, 'token_type': 'Bearer', 'expires_in': 3600, 'id_token': <ID_TOKEN>}
    <FC_URL>/api/v1/userinfo [Web Service]

    DESCRIPTION

    Contexte : Le FS a récupéré un access token. Il veut maintenant récupérer les USER INFO.
    Origine : FS
    Cible : FC
    Type d'appel : appel de Web service

    REQUETE

    URL:
    <FC_URL>/api/v1/userinfo?schema=openid
    Méthode : GET
    Entêtes HTTP : Authorization = 'Bearer <ACCESS_TOKEN>'

    REPONSE

    Corps HTTP:

    <USER_INFO>
    Données usager

    LISTE DES SCOPES DISPONIBLES LORS DE L'ETAPE D'AUTHENTIFICATION FRANCEONNECT

    FranceConnect a changé son mécanisme de scopes pour qu'il soit plus modulaire.

    • Un seul scope obligatoire : openid. Il permet de récupérer le sub (identifiant 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

    FRANCECONNECT PARTICULIER



    Les scopes principaux (identité pivot)


    • openid * : l'identifiant technique (sub) de l'utilisateur au format OpenIDConnect sera retourné
    • gender : le sexe de la personne sera retourné
    • birthdate : la date de naissance de la personne sera retourné
    • birthcountry : le pays de naissance de la personne sera retourné
    • birthplace : la ville de naissance de la personne sera retourné
    • given_name : les prénoms de la personne seront retournés
    • family_name : le nom de naissance de la personne sera retourné
    • email : l'adresse e-mail de la personne sera retourné

    Les scopes optionnels (information renvoyée si elle est disponible)


    • preferred_username : le nom d'usage de la personne sera retourné
    • address : l'adresse postale de la personne sera retourné
    • phone : le numéro de téléphone de la personne sera retourné

    Les "alias"


    • identite_pivot : Regroupe les scopes given_name, family_name, preferred_username, birthdate, gender, birthplace et birthcountry
    • profile : Regroupe les scopes given_name, family_name, preferred_username, birthdate et gender
    • birth : Regroupe les scopes birthplace et birthcountry. Permet de récupérer la ville et le département de naissance de la personne.

    FRANCECONNECT ENTREPRISE



    • openid *: l'identifiant technique (sub) de l'utilisateur au format OpenIDConnect sera retourné
    • profile * : permet de récupérer l'identité pivot. Si disponible, renvoie aussi le "preferred_username"

    * obligatoire

    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.

    • connexion avec FranceConnect
    • connexion avec FranceConnect
    • connexion avec FranceConnect
    • connexion avec FranceConnect

    Téléchargements :

    Intégration du kit FranceConnect

    Ce que nous appelons le "Kit FranceConnect" est le script qu'il est possible d'inclure (en tant que Fournisseur de Service) afin de disposer du bouton de déconnexion ainsi que du lien vers les traces. Le kit propose un menu présentant divers liens liés à FranceConnect (aujourd'hui le bouton de déconnexion et l'accès à la page "traces")

    Kit FC après connexion - cliquez sur l'utilisateur


    1. Inclure la librarie javascript FranceConnect en bas de page :
      <script src="http://fcp.integ01.dev-franceconnect.fr/js/franceconnect.js"></script>
    2. Insérer dans le code HTML la structure suivante :
      <div id="fconnect-profile" data-fc-logout-url="/lien-deconnexion"><a href="#"> le nom de l'utilisateur connecté* </a></div>
    3. Paramétrer les variables :

      data-fc-logout-url Mettre le lien de déconnexion
      Utilisateur Remplacer par le nom de l'utilisateur connecté

    Il est nécessaire que l'utilisateur soit connecté à FranceConnect pour afficher ce bloc.

    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 :

    http://fcp.integ01.dev-franceconnect.fr/api/v1/authorize?response_type=code&client_id=123456&redirect_uri=http%3A%2F%2Ffsp1.dev.dev-franceconnect.fr%2Foidc_callback%3Ftestkey%3Dtestvalue&scope=openid%20profile%20email%20address%20phone%20preferred_username%20email%20address%20phone%20preferred_username&acr_values=eidas

    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 : authentification "two factor")
    • eidas3 : niveau fort (exemple : utilisation de certificats, lecteurs de cartes ...)

    Si le claim n'est pas précisé, FranceConnect ne filtre pas les FIs selon le niveau eIDAS.
    Si un niveau est précisé, FranceConnect ne proposera à l'utilisateur que les fournisseurs d'identité de niveau supérieur ou égal.
    Aujourd'hui, 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 (claim inconnu, composition de plusieurs niveaux eidas ...), il propose une mire de choix de FIs présentant tous les FIs actifs disponibles.

  • 3

    Je veux déconnecter l'utilisateur de FranceConnect

    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

    Le FS doit proposer la déconnexion de FranceConnect à son utilisateur. 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, puis le rediriger vers la page de déconnexion de FC : <FC_URL>/api/v1/logout
    • Selon le choix de l'utilisateur, il est éventuellement déconnecté du service 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 [Redirection]

    REQUETE

    URL:
    <FC_URL>/api/v1/logout?id_token_hint=<ID_TOKEN_HINT>&state=<STATE>&post_logout_redirect_uri=<POST_LOGOUT_REDIRECT_URI>
    Méthode : GET
  • 4

    Je veux récupérer des ressources auprès d'un FD qui utilise FranceConnect

    • Ajouter votre URL de callback en modifiant vos paramètres ici. Si vous n'êtes pas déjà fournisseur de service pour la partie OpenID Connect, nous vous enverrons un client ID et un client secret.
    • Obtenir un client OAuth2.
    • Connaitre un FD intégré avec FranceConnect. Ce FD doit communiquer les ressources qu'il expose, et les scopes associés à chaque ressource.


    FranceConnect Particulier
    Authorization https://fcp.integ01.dev-franceconnect.fr/api/v1/authorize
    Token https://fcp.integ01.dev-franceconnect.fr/api/v1/token

    FranceConnect Entreprise
    Authorization https://fce.integ01.dev-franceconnect.fr/api/v1/authorize
    Token https://fce.integ01.dev-franceconnect.fr/api/v1/token

    Détail du fonctionnement
                            title Récupération de données auprès d'un FD
    
                            note right of Utilisateur
                                Début de démarche ayant besoin
                                de l'accès aux données d'un FD
                                on considère ici que l'utilisateur
                                est connecté à FC
                            end note
    
                            Utilisateur->FS: GET <FS_URL>/url-demarche
                            FS-->Utilisateur: Redirect 302 <FC_URL>/api/v1/authorize
    
                            Utilisateur->FC: GET <FC_URL>/api/v1/authorize
    
                            note right of FC
                                Redirect vers la page de
                                consentements si nécessaire
                            end note
    
                            FC-->Utilisateur: Redirect 302 <FC_URL>/consent
                            Utilisateur->FC: GET <FC_URL>/consent
                            FC->Utilisateur: formulaire de consentement
                            Utilisateur->FC: POST <FC_URL>/consent
    
                            FC-->Utilisateur: Redirect 302 <FS_URL>/<CALLBACK_URL_DATA>
                            Utilisateur->FS: GET <FS_URL>/<CALLBACK_URL_DATA>
    
                            FS->FC: POST <FC_URL>/api/v1/token
    
                            FC->FS: HTTP Response 200
    
                            FS->+FD: GET <FD_URL>/<DATA_ENDPOINT>
    
                            FD->-FS: HTTP Response 200
    
                            note right of Utilisateur
                                Infos récupérées la demande
                                peut se poursuivre
                            end note
                        

    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> [Redirection]

    DESCRIPTION

    Contexte : L'internaute accède à la page lui permettant d'effectuer une démarche en ligne via FranceConnect.
    Origine : FS
    Cible : FS
    Type d'appel : Redirection navigateur

    REQUETE

    URL :
    <FS_URL>/<url-demarche>
    Méthode : GET

    REPONSE

    /

    <FC_URL>/api/v1/authorize [Redirection]

    DESCRIPTION

    Contexte : L'internaute a besoin d'accéder à une ressource mise à disposition par un FD. Il commence donc par demander un jeton à FC. FS doit le rediriger vers le /api/v1/authorize de FC.
    Origine : FS
    Cible : FC
    Type d'appel : Redirection navigateur

    REQUETE

    URL :
    <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>
    Méthode : GET

    REPONSE

    /

    <FC_URL>/consent (GET) [Redirection]

    DESCRIPTION

    Contexte : Le FS a fait la requête d'autorisation, mais l'utilisateur n'a pas encore donné son consentement. FC redirige vers sa page de consentement.
    Origine : FC
    Cible : FC
    Type d'appel : Redirection navigateur

    REQUETE

    URL :
    <FC_URL>/consent?return_url=%2Fuser%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D<CLIENT_ID>%26scope%3D<SCOPES>%26redirect_uri%3D<CALLBACK_URL_DATA>
    Méthode : GET

    REPONSE

    Page HTML, formulaire de consentement

    <FC_URL>/consent (POST) [Redirection]

    DESCRIPTION

    Contexte : L'utilisateur accepte donne son consentement, en cliquant sur le bouton "Accepter". FC soumet le formulaire puis redirige vers le CALLBACK_URL_DATA du FS.
    Origine : FC
    Cible : FC
    Type d'appel : Redirection navigateur

    REQUETE

    URL :
    <FC_URL>/consent?return_url=%2Fuser%2Fauthorize%3Fresponse_type%3Dcode%26client_id%3D<CLIENT_ID>%26scope%3D<SCOPES>%26redirect_uri%3D<CALLBACK_URL_DATA>
    Méthode : POST

    REPONSE

    HTTP 302 - Redirection vers <FS_URL>?code=xxx

    <FS_URL>/<CALLBACK_URL_DATA> [Redirection]

    DESCRIPTION

    Contexte : L'internaute a accepté le consentement, FC appelle le callback du FS avec un code d'autorisation dans l'URL.
    Origine : FC
    Cible : FS
    Type d'appel : redirection navigateur

    REQUETE

    URL :
    <CALLBACK_URL_DATA>?code=<AUTHZ_CODE>&state=<STATE>
    Méthode : GET

    REPONSE

    /

    <FC_URL>/api/v1/token [Web Service]

    DESCRIPTION

    Contexte : Le FS a reçu le code d'autorisation. Il doit maintenant demander un access token à FC.
    Origine : FS
    Cible : FC
    Type d'appel : appel de web service

    REQUETE

    URL :
    <FC_URL>/api/v1/token
    Méthode : POST Corps HTTP :
    • 'grant_type': 'authorization_code',
    • 'redirect_uri': '<FS_URL>/<CALLBACK_URL_DATA>',
    • 'client_id': '<CLIENT_ID>',
    • 'client_secret': '<CLIENT_SECRET>',
    • 'code': '<AUTHZ_CODE>'

    REPONSE

    Corps HTTP:
    {'access_token': <ACCESS_TOKEN>,'token_type': 'Bearer', 'expires_in': 3600}
    <FD_URL>/<DATA_ENDPOINT> [Web Service]

    DESCRIPTION

    Contexte : Le FS interroge le FD selon les conventions définies avec lui (headers, query http ...).
    Origine : FS
    Cible : FD
    Type d'appel : appel de web service

    REQUETE

    URL :
     <FD_URL>/<DATA_ENDPOINT>
    Méthode : <dépend du FD>. Cependant, il faut lui passer dans cet appel l'access token reçu dans la requête précédente. Le passage se fait selon une méthode définie par le FD.

    REPONSE

    Corps HTTP:

    les données demandées (dépend du formatage des données par le FD)

    Exemple de récupération des données d'un FD fictif (DGFIP) par un FS

    Afin de vous aider dans votre implémentation de récupération des données d'un FD en tant que FS, nous avons mis en place un FD fictif reproduisant les appels de l'API DGFIP.

    En tout premier lieu, vous devez implémenter la cinématique décrite en section 4 "Je veux récupérer des ressources auprès d'un FD qui utilise FranceConnect".

    Pour simuler un appel au FD DGFIP fictif, vous devrez créer un jeu de données utilisateurs à travers l'url suivante : https://fip1.integ01.dev-franceconnect.fr/user/create

    Vous pourrez dès lors appeler le FD via les web services suivants :

    https://fdp.integ01.dev-franceconnect.fr/universelle/os1/<year> [Web Service]

    DESCRIPTION

    Contexte : Le FS interroge le FD fictif DGFIP.
    Origine : FS
    Cible : FD
    Type d'appel : appel de web service

    REQUETE

    URL :
     https://fdp.integ01.dev-franceconnect.fr/universelle/os1/<year>
    Pour l'appel de test vous ne récupérerez des données qui si l'année n'est pas postérieure à l'année courante.
    Méthode : Il faut passer dans cet appel l'access token reçu dans la requête précédente dans le header.

    SCOPES

    • dgfip_rfr: revenu fiscal de référence
    • dgfip_sitfam : situation familiale
    • dgfip_nbpac : nombre de personnes à charge
    • dgfip_nbpart : nombre de parts

    REPONSE

    Corps HTTP:
    {"rfr":50000,"sitFam":"M","nbPart":1,"pac":{"nbPac":2}}
    • rfr : Revenu fiscal de référence
    • sitFam : situation familiale
    • nbPart : nombre de parts
    • nbPac : Nombre de personnes à charge
    https://fdp.integ01.dev-franceconnect.fr/impotsparticuliers/os1/<year> [Web Service]

    DESCRIPTION

    Contexte : Le FS interroge le FD fictif DGFIP.
    Origine : FS
    Cible : FD
    Type d'appel : appel de web service

    REQUETE

    URL :
     https://fdp.integ01.dev-franceconnect.fr/impotsparticuliers/os1/<year>
    Pour l'appel de test vous ne récupérerez des données qui si l'année n'est pas postérieure à l'année courante.
    Méthode : Il faut passer dans cet appel l'access token reçu dans la requête précédente dans le header.

    SCOPES

    • dgfip_rfr: revenu fiscal de référence
    • dgfip_nbpart : nombre de parts

    REPONSE

    Corps HTTP:
    {"rfr":50000,"nbPart":1}
    • rfr : Revenu fiscal de référence
    • nbPart : nombre de parts
    https://fdp.integ01.dev-franceconnect.fr/impotsparticuliers/os2/<year> [Web Service]

    DESCRIPTION

    Contexte : Le FS interroge le FD fictif DGFIP.
    Origine : FS
    Cible : FD
    Type d'appel : appel de web service

    REQUETE

    URL :
     https://fdp.integ01.dev-franceconnect.fr/impotsparticuliers/os2/<year>
    Pour l'appel de test vous ne récupérerez des données qui si l'année n'est pas postérieure à l'année courante.
    Méthode : Il faut passer dans cet appel l'access token reçu dans la requête précédente dans le header.

    SCOPES

    • dgfip_aft: adresse fiscale de taxation

    REPONSE

    Corps HTTP:
    {"aft":"137 avenue du Général Leclerc 75014 Paris"}
    • aft : Adresse fiscale de taxation pour l'impôt sur le revenu

    Hors implémentation, vous pouvez tester la réponse reçue suite aux appels de ces webservices en vous connectant avec l'un des comptes de test créé sur l'une des plateformes d'intégration disponibles (exemple : https://guichet-parisien.integ01.dev-franceconnect.fr). Vous obtiendrez la réponse en acceptant les consentements demandés, respectivement pour les trois appels :

  • 5

    Gestion d'erreurs entre FranceConnect et le FS

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

  • 6

    Les données de FranceConnect qui expirent

    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 :

    Type Utilisé lors de ... Durée de vie
    Session Web A chaque authentification et pour maintenir la session côté FranceConnect 30 minutes sans action
    Access Token Récupération d'informations (phase 3 cinématique d'authentification / cinématique OAuth2) 20 minutes
    Authorization code Code fourni lors du début de la démarche d'authentification, il sert ensuite à récupérer l'access token 5 minutes
    Consentement Consentement donné par l'utilisateur pour l'accès à une ressource protégée (associée à un scope au sens OAuth2) 5 secondes
  • 7

    Recette d'intégration de FranceConnect

    CONNEXION / CREATION DE COMPTE



    • Afin de pouvoir réaliser des démarches chez un fournisseur de service
    • En tant qu' internaute
    • Je veux pouvoir créer un compte FranceConnect

    Affichage de la mire FranceConnect (Cas passant)



    • Sachant que je suis sur la page d'inscription du fournisseur de service
    • Et que je vois le bouton FranceConnect
    • Quand je clique sur le bouton FranceConnect
    • Alors je dois voir la mire FranceConnect apparaître

    Affichage de la mire d'authentification d'un fournisseur d'identité (Cas passant)



    • Sachant que je suis sur la mire FranceConnect
    • Et que je vois un logo d'un fournisseur d'identité
    • Quand je clique sur le logo d'un fournisseur d'identité
    • Alors je dois être redirigé vers la page d'authentification du fournisseur d'identitié

    Authentification/identification via un fournisseur d'identité (Cas passant)



    • Sachant que je suis sur la page d'authentification d'un fournisseur d'identité
    • Et que j'indique mon login dans le champ correspondant
    • Et que j'indique mon mot de passe dans le champ mot de passe
    • Quand je clique sur le bouton "valider"
    • Alors je dois être redirigé vers la page d'accueil du fournisseur de service
    • Et je dois voir mon nom
    • Et je dois voir mon prénom
    • Et je ne dois plus voir le bouton FranceConnect

    Authentification/identification via un fournisseur d'identité avec un mauvais mot de passe (Cas non passant)



    • Sachant que je suis sur la page d'authentification d'un fournisseur d'identité
    • Et que j'indique mon login dans le champ correspondant
    • Et que j'indique un mauvais mot de passe dans le champ mot de passe
    • Quand je clique sur le bouton valider
    • Alors je ne dois pas être redirigé vers la page d'accueil du fournisseur de service
    • Et je dois rester sur la page d'authentification du fournisseur d'identité

    KIT DE CONNEXION FRANCECONNECT



    • Afin de pouvoir utiliser mon compte FranceConnect
    • En tant qu' utilisateur connecté
    • Je veux pouvoir accèder aux fonctionnalités de mon compte FranceConnect

    Affichage du menu utilisateur (Cas passant)



    • Sachant que je suis connecté à FranceConnect via un fournisseur d'identité
    • Et que je vois un lien avec mon prénom et mon nom
    • Quand je clique sur ce lien
    • Alors je dois voir afficher un menu déroulant
    • Et je dois voir "Vous êtes identifié grâce à FranceConnect"
    • Et je dois voir un lien "Qu'est-ce-que FranceConnect ?"
    • Et je dois voir un lien "Historique des connexions/échanges de données"
    • Et je dois voir un bouton "Se déconnecter"

    DECONNEXION



    • Afin de pouvoir être l'unique utilisateur de mon compte
    • En tant qu' utilisateur connecté
    • Je veux pouvoir me déconnecter de mon compte FranceConnect

    Affichage de la mire de déconnexion (Cas passant)



    • Sachant que je suis connecté à FranceConnect via un fournisseur d'identité
    • Et que je clique sur le lien avec mon prénom et mon nom
    • Quand je clique sur le bouton "Se déconnecter"
    • Alors je dois être redirigé vers une mire de déconnexion
    • Et je dois voir afficher "Souhaitez-vous vous déconnecter du service FranceConnect ?"
    • Et je dois voir le bouton "Oui"
    • Et je dois voir le bouton "Non"

    Affichage du message de déconnexion définitif (Cas passant)



    • Sachant que je suis sur la mire de déconnexion
    • Quand je clique sur le bouton "Se déconnecter"
    • Alors je dois voir le message "Merci de fermer le navigateur pour garantir une parfaite déconnexion"

    Déconnexion non définitive à FranceConnect (Cas passant)



    • Sachant que je vois le message de parfaite déconnexion
    • Quand je clique à l'extérieur du message "Merci de fermer le navigateur pour garantir une parfaite déconnexion"
    • Alors je suis redirigé vers la page d'accueil du fournisseur de service

    La déconnexion doit être totale si la durée de navigation est supérieure à 2 minutes (Cas passant)



    • Sachant que je me suis déconnecté de manière non définitive à FranceConnect
    • Et que je suis sur la page d'accueil
    • Et que j'avais navigué plus de 2 minutes sur le fournisseur de service
    • Quand je clique sur le bouton FranceConnect
    • Alors je dois voir la mire FranceConnect apparaître
    • Et je clique sur le même fournisseur d'identité que précédemment
    • Alors je dois être redirigé vers la mire d'authentification de ce fournisseur d'identitié
    • Et je dois voir le label d'identification avec le champ de saisie correspondant
    • Et je dois voir le label "mot de passe" avec le champ de saisie correspondant

    SSO



    • Afin de pouvoir éviter de me reconnecter à un site disposant de FranceConnect
    • En tant qu' internaute
    • Je veux pouvoir bénéficier du SSO

    Connexion via SSO (Cas passant)



    • Sachant que je suis connecté à FranceConnect via un fournisseur d'identité
    • Et que j'ouvre un nouvel onglet dans mon navigateur
    • Et que je visite un autre fournisseur de service
    • Quand je clique sur le bouton FranceConnect du deuxième fournisseur de service
    • Alors je ne dois pas voir la mire FranceConnect apparaître
    • Et je dois voir un lien avec mon prénom et mon nom

    Déconnexion via SSO (Cas passant)



    • Sachant que je suis connecté à FranceConnect via fournisseur d'identité
    • Et que je suis connecté à un autre fournisseur de service dans un nouvel onglet
    • Quand je clique sur le bouton "Se déconnecter" du premier fournisseur de service
    • Alors je dois être redirigé vers une mire de déconnexion
    • Et je dois voir afficher "Souhaitez-vous vous déconnecter du service FranceConnect ?"
    • Quand je clique sur le bouton "Oui"
    • Alors je dois voir le message "Merci de fermer le navigateur pour garantir une parfaite déconnexion"
    • Quand je clique à l'extérieur du message
    • Et que je visite l'autre fournisseur d'identité
    • Alors je ne dois pas voir mon nom et mon prénom apparaître

    RAPPROCHEMENT DE COMPTE



    • Afin de pouvoir bénéficier des avantages de FranceConnect
    • En tant qu' internaute
    • Je veux pouvoir lier mon compte local avec mon compte FranceConnect

    Association de compte (Cas passant)



    • Sachant que je possède un compte local auprès d'un fournisseur de service
    • Et que je ne possède pas de compte FranceConnect
    • Et que je suis connecté avec ce compte local
    • Et que je suis sur la page d'édition de mon profil
    • Alors je dois voir "certifier mon compte FranceConnect"
    • Quand je clique sur le bouton "certifier mon compte FranceConnect"
    • Alors je dois voir la mire FranceConnect apparaître
    • Quand je clique sur le logo d'un fournisseur d'identité
    • Alors je dois être redirigé vers la mire d'authentification de ce fournisseur d'identitié
    • Quand j'indique mon login dans le champ correspondant
    • Et que j'indique mon mot de passe dans le champ mot de passe
    • Et que je clique sur le bouton "valider"
    • Alors je dois être redirigé vers la page d'édition de mon profil
    • Et je ne dois pas voir "certifier mon compte FranceConnect"
    • Et je dois voir "Dissocier mon compte de France Connect"

    Dissociation de compte (Cas passant)



    • Sachant que je possède un compte local et un compte FranceConnect auprès d'un fournisseur de service
    • Et que je suis connecté avec mon compte FranceConnect
    • Quand je clique sur le bouton "Dissocier mon compte de FranceConnect"
    • Alors je dois être redirigé vers une mire de déconnexion
    • Et je dois voir "Souhaitez-vous vous déconnecter du service FranceConnect ?"
    • Et je dois voir un bouton "Oui"
    • Et je dois voir un bouton "Non"
    • Quand je clique sur le bouton "Oui"
    • Alors je dois voir le message "Merci de fermer le navigateur pour garantir une parfaite déconnexion"
    • Quand je clique à l'extérieur du message
    • Alors je dois être redirigé vers la page d'édition de mon profil
    • Et je dois voir "certifier mon compte FranceConnect"

    Impossibilité d'associer plusieurs comptes FranceConnect (Cas passant)



    • Sachant que je possède un compte local et un compte FranceConnect auprès d'un fournisseur de service
    • Et que je suis connecté avec mon compte FranceConnect
    • Quand j'indique l'url https://app.franceconnect.gouv.fr/api/v1/authorize?response_type=code&client_id=<client_id>redirect_uri=<redirect_uri>&scope=<scope>&state=<state>&nonce=<nonce>
    • Alors je dois être redirigé vers la page d'édition de profil FranceConnect

    IDENTITE PIVOT



    • Afin de pouvoir gagner du temps
    • En tant qu' internaute
    • Je veux que FranceConnect transmette mes informations pivot au fournisseur de service dans le cadre d'une démarche

    Utilisation des données pivot dans le cadre d'une démarche sans consentement (Cas passant)



    • Sachant que je suis connecté à un fournisseur de service avec mon compte FranceConnect
    • Et que je commence ma démarche
    • Si ma démarche nécessite mon "nom"
    • Alors le champ doit indiquer mon "nom"
    • Et je ne peux pas modifier la valeur du champ "nom"
    • Si ma démarche nécessite mon "nom d'usage"
    • Alors le champ doit indiquer mon "nom d'usage" si je dispose de cette information
    • Et je ne peux pas modifier la valeur du champ "nom d'usage" si elle provient de FranceConnect
    • Si ma démarche nécessite mon "prénom"
    • Alors le champ doit indiquer mon "prénom"
    • Et je ne peux pas modifier la valeur du champ "prénom"
    • Si ma démarche nécessite ma "date de naissance"
    • Alors le champ doit indiquer ma "date de naissance"
    • Et je ne peux pas modifier la valeur du champ "date de naissance"
    • Si ma démarche nécessite ma "civilité"
    • Alors le champ doit indiquer ma "civilité"
    • Et je ne peux pas modifier la valeur du champ "civilité"
    • Si ma démarche nécessite mon "pays de naissance"
    • Alors le champ doit indiquer mon "pays de naissance"
    • Et je ne peux pas modifier la valeur du champ "pays de naissance"
    • Si ma démarche nécessite ma "ville de naissance"
    • Alors le champ doit indiquer ma "ville de naissance"
    • Et je ne peux pas modifier la valeur du champ "ville de naissance"
    • Si ma démarche nécessite mon "adresse email"
    • Alors le champ doit indiquer mon "adresse email" si je dispose de cette information
    • Et je ne peux pas modifier la valeur du champ "adress email" si elle provient de FranceConnect
    • Si ma démarche nécessite mon "adresse"
    • Alors le champ doit indiquer mon "adresse" si je dispose de cette information
    • Et je ne peux pas modifier la valeur du champ "adresse" si elle provient de FranceConnect
    • Si ma démarche nécessite mon "téléphone"
    • Alors le champ doit indiquer mon "téléphone" si je dispose de cette information
    • Et je ne peux pas modifier la valeur du champ "téléphone" si elle provient de FranceConnect

    CONSENTEMENT



    • Afin de pouvoir donner mon accord concernant la transmission de données
    • En tant qu' internaute
    • Je veux que FranceConnect me donne le choix d'acquiesser à cette demande

    TRACES



    • Afin de pouvoir voir mon historique
    • En tant qu' internaute
    • Je veux que FranceConnect me donne la possibilité de visualiser celles-ci

    Affichage de la trace "connexion" (Cas passant)



    • Sachant que je viens de me connecter à un fournisseur de service avec mon compte FranceConnect
    • Et que je clique sur le lien avec mon nom et mon prénom
    • Et que je clique sur "Historique des connexions/échanges de données"
    • Alors je dois voir une popup s'afficher
    • Et la popup doit avoir le titre "Historique des connexions et des échanges de données"
    • Et je dois voir "Connexion" et le nom du fournisseur de service
    • Et je dois voir la date d'aujourd'hui et l'heure à laquelle je me suis connecté
    • Et je dois voir le nom du fournisseur d'identité avec lequel je me suis connecté
    • Et je dois voir ma géolocalisation
    • Et je dois voir le niveau de sécurité eidas du fournisseur de service

    Affichage de la trace "autorisation" (Cas passant)



    • Sachant que je viens d'effectuer une démarche en ligne ayant nécessitée le consentement suivant:
      • Adresse Postale (EDF)
      • Revenu fiscal de référence (Impôts)
      • Nombre de parts (Impôts)
      • Coordonnées bancaires : BIC et IBAN (Impôts)
    • Et que je clique sur le lien avec mon nom et mon prénom
    • Et que je clique sur "Historique des connexions/échanges de données"
    • Alors je dois voir une popup s'afficher
    • Et la popup doit avoir le titre "Historique des connexions et des échanges de données"
    • Et je dois voir "Autorisation"
    • Et je dois voir le nom du fournisseur de service
    • Et je dois voir le nombre de données auxquelles j'ai donné mon consentement
    • Et je dois voir Vous avez accordé la récupération de votre Adresse Postale (EDF)
    • Et je dois voir Vous avez accordé la récupération de votre Revenu fiscal de référence (Impôts)
    • Et je dois voir Vous avez accordé la récupération de votre Nombre de parts (Impôts)
    • Et je dois voir Vous avez accordé la récupération de votre Coordonnées bancaires : BIC et IBAN (Impôts)

    Affichage de la trace "Données échangées" (Cas passant)



    • Sachant que je viens d'effectuer une démarche en ligne ayant nécessitée le consentement suivant:
      • Adresse Postale (EDF)
      • Revenu fiscal de référence (Impôts)
      • Nombre de parts (Impôts)
      • Coordonnées bancaires : BIC et IBAN (Impôts)
    • Et que je clique sur le lien avec mon nom et mon prénom
    • Et que je clique sur "Historique des connexions/échanges de données"
    • Alors je dois voir une popup s'afficher
    • Et la popup doit avoir le titre "Historique des connexions et des échanges de données"
    • Et je dois voir "Données échangées"
    • Et je dois voir le nom du fournisseur de service
    • Et je dois voir le nombre de données qui ont été transmises
    • Et je dois voir Vous avez accordé la récupération de votre Adresse Postale (EDF)
    • Et je dois voir "Récupération de votre Revenu fiscal de référence (Impôts)"
    • Et je dois voir "Récupération de votre Attestation de droit (Assurance Maladie)"
    • Et je dois voir "Récupération de votre Adresse Postale (EDF)"
  • 8

    Glossaire

    FC_URL URL de FranceConnect
    FS_URL Votre URL, en tant que fournisseur de service
    FD_URL URL du fournisseur de données
    CALLBACK_URL_DATA le callback du FS, communiqué lors de son inscription auprès de FC
    DATA_ENDPOINT Endpoint sur lequel le FD expose sa ressource. Il doit être communiqué par le FD
    POST_LOGOUT_REDIRECT_URI L'URL de redirection après la demande de déconnexion FC
    CLIENT_ID Identifiant du FS, communiqué lors de son inscription auprès de FC
    CLIENT_SECRET Le secret du FS, communiqué lors de son inscription auprès de FC
    AUTHZ_CODE Code retourné (dans l'URL) par FC au FS lorsque ce dernier fait un appel sur le endpoint FC_URL/api/v1/authorize. Il est ensuite passé (dans le corps de la requête HTTP POST) lors de l'appel sur le endpoint FC_URL/api/v1/token
    ACCESS_TOKEN Token retourné (dans le corps HTTP) par l'appel au endpoint FC_URL/api/v1/token. Il est ensuite passé lors de l'appel au endpoint FC_URL/api/v1/userinfo
    SCOPES

    Liste des scopes demandés séparés par des espaces (donc par %20 au format unicode dans l'URL). Voici la liste supportée par FranceConnect

    • openid : obligatoire, permet de demander l'identifiant technique de l'utilisateur au formatOpenIDConnect
    • profile : obligatoire, permet de récupérer l'essentiel de l'identité pivot. Si disponible, renvoie aussi le preferred_username
    • birth : obligatoire, permet de récupérer la ville et le département de naissance de la personne (identité pivot)
    • email : facultatif, si disponible, renvoie l'adresse e-mail de la personne
    • address : facultatif, si disponible, renvoie l'adresse postale de la personne
    • phone : facultatif, si disponible, renvoie le numéro de téléphone de la personne
    Cette liste de scopes est définie par la norme OpenIDConnect
    L'identité pivot complète se récupère par deux scopes différents (profile + birth) car les informations de ville et de département de naissance de la personne ne font pas partie des données pouvant être renvoyées en soumettant le scope 'profile' seul. Le découpage est fait ici dans un souci de se conformer à la norme.

    ID_TOKEN

    Objet JWT retourné par l'appel au endpoint FC_URL/api/v1/token. L'objet JWT est un objet JSON formatté et signé. Le JSON doit contenir ces six clés : aud,exp,iat,iss,sub et nonce.

    Exemple :

    {'aud':'895fae591ccae777094931e269e46447', 'exp':1412953984, 'iat':1412950384, 'iss':http://franceconnect.gouv.fr, 'sub':YWxhY3JpdMOp, 'idp':'FC', 'nonce':'12344354597459'}

    Détail des champs :

    • aud, exp, iat, iss, sub : ce sont des champs obligatoires de la norme OpenIDConnect
    • nonce : paramètre obligatoirement envoyé lors de l'appel à /authorization. Le FS doit impérativement vérifier que la valeur correspond bien à celle qu'il a envoyée, et qui doit être liée à la session de l'utilisateur

    Si vous utilisez une librairie pour transformer le json en JWT, il génèrera une chaîne de caractères constitué de 3 chaînes base64 séparées par un point.

    Pour vérifier la signature, il faut utiliser le secret partagé avec FranceConnect (qui vous a été attribué lors de votre provisioning côté FC)

    ID_TOKEN_HINT

    Objet JWT identique au format ID_TOKEN qui a été reçu lors de l'échange avec l'appel à FC_URL/api/v1/token et doit être passé en paramètre lors de l'appel à FC_URL/api/v1/logout

    USER_INFO Voir la section identité pivot
    STATE Champ obligatoire, généré aléatoirement par le FS, que FC renvoie tel quel dans la redirection qui suit l'authentification, pour être ensuite vérifié par le FS. Il est utilisé afin d’empêcher l’exploitation de failles CSRF
    NONCE Champ obligatoire, généré aléatoirement par le FS que FC renvoie tel quel dans la réponse à l'appel à /token, pour être ensuite vérifié par le FS. Il est utilisé pour empêcher les attaques par rejeu
    SUB Identifiant technique (unique et stable dans le temps pour un individu donné) fourni par FranceConnect au FS. Le sub est présent dans l'IdToken retourné au FS ainsi que dans les informations d'identité. Le sub retourné par FranceConnect est spécifique à chaque fournisseur de service (i.e: Un usager aura toujours le même sub pour un FS donné, en revanche il aura un sub différent par FS qu'il utilise).