Documentation

Fournisseur d'identité

  • 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
    sub string identifiant technique (standard OpenIDConnect)
    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 sur 5 chiffres (ou une chaîne vide si la personne est née à l'étranger)
    birthcountry string le code INSEE du pays de naissance sur 5 chiffres

    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 être founisseur d'identité FranceConnect

    • Enregistrer FranceConnect comme client avec notre URL de callback et vous inscrire en tant que FI via ce formulaire.
    • Obtenir un fournisseur (provider) OpenID Connect
    • Nous faire parvenir un logo !
    Nos Endpoints

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

    FranceConnect doit être capable d'interroger le FI. Pensez à configurer votre proxy, si nécessaire, pour autoriser l'accès Internet depuis FC.

    FranceConnect Particulier
    https://fcp.integ01.dev-franceconnect.fr/oidc_callback

    FranceConnect Entreprise
    https://fce.integ01.dev-franceconnect.fr/oidc_callback

    Détail du fonctionnement
                              title Séquence d'authentification (Fournisseur d'identité)
    
                              note right of Utilisateur
                                  L'utilisateur a choisi son FI
                                  FC redirige sur celui-ci
                              end note
    
                              FC-->Utilisateur: Redirect 302 <FI_URL>/user/authorize
                              Utilisateur->FI: GET <FI_URL>/user/authorize
    
                              note left of FI
                                  Authentification de l'utilisateur par le FI
                                  Implémentation spécifique au FI
                              end note
    
                              FI-->Utilisateur: Redirect 302 <FC_URL>/oidc_callback
                              Utilisateur->FC: GET <FC_URL>/oidc_callback
    
                              FC->FI: POST <FC_URL>/user/token
    
                              FI->FC: HTTP Response 200
    
                              FC->FI: GET <FC_URL>/api/user
    
                              FI->FC: HTTP Response 200
    
                              note right of Utilisateur
                                  FranceConnect fournit le service
                                  à l'utilisateur
                              end note
                          
    Détail des flux
    <FI_URL>/user/authorize [Redirection]

    DESCRIPTION

    Contexte : L'internaute a cliqué sur le fournisseur d'identité de son choix. FC redirige vers le /user/authorize du FI.
    Origine : FC
    Cible : FI
    Type d'appel : Redirection navigateur

    REQUETE

    URL:

    <FI_URL>/user/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<FC_URL>%2Foidc_callback&scope=<SCOPES>&state=<STATE>&nonce=<NONCE>&acr_values=<ACR_VALUES>
    Méthode : GET


    REPONSE

    /

    <FC_URL>/oidc_callback [Redirection]

    DESCRIPTION

    Contexte : Le FI redirige vers le callback du FC.
    Origine : FI
    Cible : FC
    Type d'appel : redirection navigateur


    REQUETE

    URL:
    <FC_URL>/oidc_callback?code=<AUTHZ_CODE>&state=<STATE>
    Méthode : GET

    REPONSE

    /

    <FI_URL>/user/token [Web Service]

    DESCRIPTION

    Contexte : Le FC fait un appel au FI pour récupérer un access token, un id token, et un refresh token.
    Origine : FC
    Cible : FI
    Type d'appel : appel de Web service


    REQUETE

    URL:
    <FI_URL>/user/token
    Méthode : POST
    Corps HTTP :
    • 'grant_type': 'authorization_code',
    • 'redirect_uri': '<FC_URL>/oidc_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, 'refresh_token': <REFRESH_TOKEN>, 'id_token': <ID_TOKEN>}
    <FI_URL>/api/user [Web Service]

    DESCRIPTION

    Contexte : Le FC fait un appel au FI pour récupérer les USER_INFO de l'internaute.
    Origine : FC
    Cible : FI
    Type d'appel : Appel de web service

    REQUETE

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

    REPONSE

    Corps HTTP:

    <USER_INFO>
    Utiliser les niveaux eIDAS en tant que FI

    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. En tant que FI, il est nécessaire de retourner à FranceConnect le niveau eIDAS avec lequel l'utilisateur vient de s'authentifier.

    De manière analogue à ce qui est fait pour demander un FI réputé utiliser un niveau eIDAS particulier à France Connect (cf la section correspondante dans la documentation FS), le FI doit signifier à FranceConnect avec quel niveau eIDAS l'authentification s'est faite.

    Dans le cadre du FI, cela se traduit par le fait de positionner le claim "acr" dans l'ID Token renvoyé au client (http://openid.net/specs/openid-connect-core-1_0.html#rfc.section.2). De la même manière que pour un FS demandant à FranceConnect de filtrer les FIs réputés compatibles avec un niveau eIDAS particulier, le claim acr retourné dans l'ID Token peut être :

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

    Cette donnée est retournée à FranceConnect, qui lui même la retourne au FS et au FD (sans la modifier).

  • 3

    La gestion d'erreurs : en tant que FI, quelles erreurs renvoyer à FC?

    En tant que FI, la gestion d'erreur est relativement simple : il faut retourner les informations d'erreur à FranceConnect (s'il y en a) par l'URL de callback fournie en utilisant le formalisme se trouvant dans la norme (exemple: http://openid.net/specs/openid-connect-core-1_0.html#AuthError).Par rapport à un FI, FranceConnect est toujours positionné en tant que client OpenID Connect, il n'est donc jamais en position de répondre quoi que ce soit à un FI.

  • 4

    Glossaire

    FC_URL URL de FranceConnect
    FI_URL Votre URL, en tant que fournisseur d'identité
    CLIENT_ID Identifiant de FC, communiqué par le FI à FC lors de son inscription.
    CLIENT_SECRET Secret de FC, communiqué par le FI à FC lors de son inscription.
    AUTHZ_CODE Code retourné (dans l'URL) par le FI à FC lorsque ce dernier fait un appel sur le endpoint FI_URL/user/authorize. Il est ensuite passé (dans le corps de la requête HTTP POST) lors de l'appel sur le endpoint FI_URL/user/token.
    ACCESS_TOKEN Token retourné (dans le corps HTTP) par l'appel au endpoint FI_URL/user/token. Il est ensuite passé lors de l'appel au endpoint FI_URL/api/user.
    REFRESH_TOKEN Token retourné (dans le corps HTTP) par l'appel au endpoint FI_URL/user/token. Il n'est pas utilisé par la suite.
    SCOPES

    Liste des scopes demandés séparés par des espaces (donc par %20 au format unicode dans l'URL). Voici la liste demandé 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
    • email : obligatoire, 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

    ID_TOKEN

    Objet JWT retourné par l'appel au endpoint <FC_URL>/user/token. L'objet JWT est un objet JSON formaté et signé. Pour l'instant, FranceConnect ne supporte que l'algorithme de signature HS256 (HMAC using SHA-256 hash algorithm). Le JSON doit contenir ces six clés : aus, exp, iat, iss, nonce, sub. La clé à utiliser pour la signature est le secret partagé avec FranceConnect (que vous lui avez attribué avec un client_id lors de son provisioning en tant que client OpenID Connect du FI)

    Notez que le champ nonce est bien obligatoire et doit obligatoirement retourner la valeur fournie par FranceConnect dans l'URL de redirection au début de la cinématique d'authentification.

    Exemple :

    {'aud':'895fae591ccae777094931e269e46447', 'exp':1412953984, 'iat':1412950384, 'iss':http://impots-franceconnect.fr, 'sub':4344343423, 'nonce':34324432468}

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

    USER_INFO Voir la section identité pivot
    STATE Champ obligatoire, généré aléatoirement par FC, que FI renvoie tel quel dans la redirection qui suit l'authentification, pour être ensuite vérifié par FC. Il est utilisé afin d’empêcher l’exploitation de failles CSRF.
    NONCE Champ obligatoire, généré aléatoirement par FC que le FI renvoie tel quel dans la réponse à l'appel à /token, pour être ensuite vérifié par FC. 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 le FI à FC. Le sub doit être présent dans l'IdToken retourné à FC ainsi que dans les informations d'identité. Pour plus d'informations sur le rôle et la description du "sub", se référer à la documentation OpenID Connect http://openid.net/specs/openid-connect-basic-1_0.html (section 2.2)
    ACR_VALUES Champ facultatif, fourni par le FS à FC et par FC au FI. Il correspond au niveau d'authentification demandé par le FS (niveau eidas). Pour plus d'informations sur le rôle et la description du champ "acr_values", se référer à la documentation OpenID Connect http://openid.net/specs/openid-connect-basic-1_0.html (section 2.1.1.1)