A propos de l'utilisation de CIBA

Le flux CIBA admet actuellement deux moyens d'authentification : la e-CPS, et la carte CPx. L'authentification par carte CPx en CIBA s'effectue avec l'outil CPS-Gestion, disponible sur les stores Microsoft et Apple. En fonction du type de carte insérée (Test ou production), l'outil adressera l'environnement de PSC correspondant (BAS ou production).

CPS-Gestion pour Windows intègre cette fonctionnalité d'authentification depuis sa version 1.3.7.

CPS-Gestion pour macOS intégrera cette fonctionnalité dans une prochaine version (travaux en cours).

Introduction à CIBA

  • Les flux OpenID Connect reposent typiquement sur des redirections au sein de navigateurs, ou bien nécessitent une interaction de l'utilisateur avec l’application.
    La spécification Client Initiated Backchannel Authentication (CIBA) étend OpenID Connect pour définir un flux découplé. Cela permet de décorréler l’appareil d’utilisation d’une application et l’appareil utilisé pour s’authentifier.
  • Ainsi, pour un utilisateur donné, le fournisseur de service peut obtenir des jetons du serveur de ressources et les transmettre sur un appareil (ex: ordinateur), alors que l'utilisateur a utilisé un autre appareil pour s'authentifier et donner son consentement (ex: smartphone).
  • CIBA permet la mise en œuvre de nombreux cas d’usages dans un flux normalisé, et bénéficie de l’assise de la norme OpenID Connect, déjà largement adoptée. En particulier, CIBA aide à se conformer aux cadres juridiques en définissant un protocole qui peut être utilisé pour mettre en œuvre une approche découplée pour l'authentification forte du client, comme décrit dans la directive européenne PSD2.
  • Le flux CIBA est particulièrement adapté aux logiciels de type client lourd et aux applications mobiles, la demande d'authentification de l'utilisateur intervenant au sein du logiciel ou de l'application, sans nécessiter l'utilisation d'un navigateur internet.
  • Les échanges de votre service avec PSC nécessitent obligatoirement un serveur intermédiaire : le client lourd ou l'application mobile ne peuvent pas échanger directement avec PSC. Les échanges entre le client lourd ou l'application mobile et ce serveur intermédiaire sont du ressort de l'industriel qui les met en œuvre.

Schéma simplifié du déroulement d'une authentification CIBA

 Les endpoints de ProSantéConnect

Environnement Intégration - Bac à sable 

EndpointURL de l'endpointUsage
Portail e-CPShttps://wallet.bas.psc.esante.gouv.frGestion de la e-CPS BAS
Discovery Endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configurationRécupération des informations de configuration
BackChannel Authentication Endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/authDémarrage de l'authentification CIBA (Authentication Request)
Token EndPointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/tokenRécupération du résultat de la demande d'authentification (CIBA Polling Request) et rafraîchissement de l'access token
User info Endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfoAccès aux ressources protégées
Introspection Endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspectIntrospection de l'access token ou du refresh token
Logout Endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logoutDéconnexion de l'utilisateur

 

Environnement de production

EndpointURL de l'endpointUsage
Portail e-CPShttps://wallet.esw.esante.gouv.fr/Gestion de la e-CPS
Discovery Endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configurationRécupération des informations de configuration
BackChannel Authentication Endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/authDémarrage de l'authentification CIBA (Authentication Request)
Token EndPointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/tokenRécupération du résultat de la demande d'authentification (CIBA Polling Request) et rafraîchissement de l'access token
User info Endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfoAccès aux ressources protégées
Introspection Endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspectIntrospection de l'access token ou du refresh token
Logout Endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logoutDéconnexion de l'utilisateur

 

Mise en oeuvre de CIBA

Seul le mode Poll est implémenté dans Pro Santé Connect parmi les 3 flux définis dans le standard CIBA : mode Poll, mode Push, mode Ping.

L'utilisation de CIBA nécessite d'avoir la fonctionnalité activée sur votre service. 
Vous pouvez demander cette activation depuis la page Gérez votre service

Demande d’authentification (CIBA Auth Endpoint)

Requête

  • Endpoint: BackChannel Authentication EndPoint
  • Contexte: Le fournisseur de service (client) lance une demande d'authentification pour un identifiant donné
  • Méthode HTTP: POST
  • Authentification: Basic Auth
  • Header: 
    Content-Type: application/x-www-form-urlencoded
     
  • Paramètres POST:
ParamètreObligatoireValeur
scopeOui"openid scope_all"

login_hint

OuiIdentifiant RPPS de la personne que l'on souhaite authentifier
binding_messageOuiNombre aléatoire à deux chiffres compris entre 00 et 99 (inclus), il doit être généré par le client, affiché à l'utilisateur, et transmis à Pro Santé Connect dans ce champ
acr_valuesOuiCe champ doit prendre la valeur "eidas1"
channelNon

Moyen d’authentification demandé :

  • "MOBILE" : La e-CPS
  • "CARD" : La carte CPx

Par défaut, si ce champ n’est pas renseigné, le moyen d’authentification utilisé sera la e-CPS

Réponse du serveur

ParamètreValeurDescription
auth_req_idJeton au format JWT

Il s'agit de l'ID unique de la demande d'authentification. Il est utilisé dans les demandes de jeton pour identifier la transaction démarrée par la demande d'authentification du client. Ainsi, le client doit conserver ce paramètre.

expires_in120

Le nombre de secondes, depuis la réception de la demande d'authentification, pendant lesquelles la demande d'authentification sera valide.

interval5Le nombre de secondes que le client doit attendre entre deux demandes d'interrogation. La valeur par défaut est 5 secondes.

Réponse JSON: 

HTTP/1.1 200 OK
...
Content-Type: application/json
{"auth_req_id":"eyJhb.......aNwIFBvI19FGD3ukDrH0BQ",
"expires_in":120,
"interval":5}

Gestion des erreurs

La liste des erreurs fonctionnelles est la suivante :

ErreurDescription

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_request",
"error_description":"invalid user"}

L'identifiant RPPS fourni dans le paramètre login_hint est inconnu.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_request",
"error_description":"invalid user: not activated"}

L’identifiant RPPS fourni dans le paramètre login_hint est connu, mais cet utilisateur n’a pas activé sa e-CPS.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_request",
"error_description":"invalid_binding_message"}

Le paramètre binding_message n’est pas présent, ou n’a pas le format attendu.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_request",
"error_description":"invalid_channel"}

Le paramètre channel n'a pas le format attendu.

La liste, non exhaustive, des erreurs techniques dues à une mauvaise configuration, est la suivante :

ErreurDescription

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"invalid_client",
"error_description":"Invalid client credentials"}

Le client_id utilisé pour l'authentification du FS est inconnu.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"unauthorized_client",
"error_description":"Invalid client secret"}

Le client_secret utilisé pour l'authentification du FS n'est pas celui attendu pour ce client_id.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"invalid_grant",
"error_description":"Client not allowed OIDC CIBA Grant"}

Le couple client_id/client_secret utilisé est valide, mais ce client_id n'est pas autorisé à faire du CIBA.

Récupération des jetons via la méthode Poll (Token Endpoint)

Pour récupérer le jeton, le FS doit venir interroger le serveur CIBA au niveau du Token Endpoint dans le délai indiqué par le paramètre "expires_in" retournée lors de la demande d'authentification.
Il peut interroger périodiquement le serveur en respectant un délai minimum défini par le paramètre "interval" retourné lors de la demande d'authentification.

Requête

Le serveur peut mettre plus de temps à répondre que l’intervalle spécifié, dans ce cas le client doit attendre une réponse et ne pas envoyer de nouvelle requête auth_req_id qui pourrait se chevaucher avec la précédente.

  • Endpoint: Token Endpoint
  • Contexte: La requête d'authentification initiale a bien été prise en compte, le client a reçu un auth_req_id, et vient interroger le serveur CIBA pour connaître l'état d'avancement de l'authentification
  • Méthode HTTP: POST
  • Authentification: Basic Auth
  • Header: Content-Type: application/x-www-form-urlencoded
  • Paramètres POST:
ParamètreObligatoireValeur
grant_typeOui

urn:openid:params:grant-type:ciba

auth_req_idOui

Valeur auth_req_id communiquée par le serveur d’authentification

Réponse du serveur

Si l'authentification a été effectuée avec succès, le serveur CIBA Pro Santé Connect renvoie sous la forme d'un JSON les informations suivantes : 

Paramètre

Description

access_tokenJeton d'accès à durée limitée
expires_inValeur entière indiquant le délai d'expiration en secondes de l'access_token 
refresh_tokenJeton permettant de rafraîchir l'access_token
refresh_expires_inValeur entière indiquant le délai d'expiration en secondes du refresh token
token_typeValeur constante : "Bearer"
id_tokenJeton d'identification
scopeListe des scopes obtenus suite à la demande d'authentification

Exemple de réponse au format JSON :

HTTP/1.1 200 OK
Content-Type: application/json
{"access_token":"eyJhbGciO....U3Oi3Q-B5zw",
"expires_in":300,
"refresh_expires_in":1800,
"refresh_token":"eyJhb....sQEw",
"token_type":"Bearer",
"id_token":"eyJhb....8VlEsA",
....,
"scope":"openid, identity, scope_all"}

Gestion des erreurs

La liste des erreurs fonctionnelles est la suivante :

ErreurDescription

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"authorization_pending",
"error_description":"The authorization request is still pending as the end-user hasn't yet been authenticated."}

La requête d’authentification est en cours, l'utilisateur n'a pas encore répondu.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"access_denied",
"error_description":"not authorized"}

L'utilisateur a refusé ou annulé la demande d'authentification.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"slow_down",
"error_description":"too early to access"}

Requête de polling prématurée, le client doit respecter l'intervalle de temps défini entre 2 requêtes.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"expired_token",
"error_description":"authentication timed out"}

Le auth_req_id utilisé a expiré, le client doit initier une nouvelle demande d'authentification.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_grant",
"error_description":"Invalid auth_req_id"}

Le auth_req_id utilisé est invalide, causes possibles :
- ce code (à usage unique) a déjà permis d’obtenir une réponse OK
- l’erreur “expired_token” a déjà été renvoyée pour ce code, ou celui-ci a expiré depuis un délai important

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_grant",
"error_description":"Invalid Auth Req ID"}

Le auth_req_id utilisé est invalide : il n’a pas été généré par Pro Santé Connect, ou a été altéré.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"invalid_grant",
"error_description":"unauthorized client"}

Le auth_req_id utilisé n’a pas été délivré à ce client_id.

La liste, non exhaustive, des erreurs techniques dues à une mauvaise configuration, est la suivante :

ErreurDescription

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"invalid_client",
"error_description":"Invalid client credentials"}

Le client_id utilisé pour l'authentification du FS est inconnu.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"unauthorized_client",
"error_description":"Invalid client secret"}

Le client_secret utilisé pour l'authentification du FS n'est pas celui attendu pour ce client_id.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"invalid_grant",
"error_description":"Client not allowed OIDC CIBA Grant"}

Le couple client_id/client_secret utilisé est valide, mais ce client_id n'est pas autorisé à faire du CIBA.

Opérations suivantes

La différence entre le flux CIBA et le flux Authorization Code Flow porte uniquement sur les modalités d'obtention des jetons access_token, refresh_token et id_token.

Les opérations suivantes (accès aux ressources protégées, UserInfo, rafraîchissement des jetons, introspection, déconnexion, ...) sont donc similaires au cas "standard", dont vous trouverez la documentation ici:
https://industriels.esante.gouv.fr/produits-et-services/pro-sante-connect/documentation-technique

Was this page useful to you?

The information you provide in this questionnaire will be saved by the ANS into a digital database in order to optimise our website and improve our services.

The information saved is only to be used by the ANS and is only accessible to its services, its staff, and third-party providers authorised to consult it.

According to the regulation applicable in terms of personal data protection, you have the right to access, modify and erase your data. To do so, you may contact our Data Protection administrator, following the conditions set out in the page Personal Data Protection Policy on the ANS website.