A propos de l'utilisation de CIBA

Le seul moyen d'authentification actuellement supporté par CIBA est la e-CPS. Des travaux sont en cours pour intégrer la carte CPx

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 OpenIdConnect, 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 PSD2.

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

 Les endpoints de ProSantéConnect

Environnement Intégration - Bac à sable 

Endpoint

URL de l'endpoint

Usage

Portail e-CPS

https://wallet.bas.psc.esante.gouv.fr

Gestion de la e-CPS BAS

Discovery Endpoint

https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration

Récupération des informations de configuration
Authorization Endpoint https://wallet.bas.psc.esante.gouv.fr/auth Démarrage de l'authentification Code Flow

BackChannel Authentication Endpoint

https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/auth

Démarrage de l'authentification CIBA (Authentication Request)

Token EndPoint

https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token

Récupération du résultat de la demande d'authentification (CIBA Polling Request) et rafraîchissement de l'access token

User info Endpoint

https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo

Accès aux ressources protégées

Introspection Endpoint

https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspect

Introspection de l'access token ou du refresh token
Logout Endpoint https://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout Déconnexion de l'utilisateur

 

Environnement de production

Endpoint

URL de l'endpoint

Usage

Portail e-CPS

https://wallet.esw.esante.gouv.fr/

Gestion de la e-CPS

Discovery Endpoint

https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration

Récupération des informations de configuration
Authorization Endpoint https://wallet.esw.esante.gouv.fr/auth Démarrage de l'authentification Code Flow

BackChannel Authentication Endpoint

https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/auth

Démarrage de l'authentification CIBA (Authentication Request)

Token EndPoint

https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token Récupération du résultat de la demande d'authentification (CIBA Polling Request) et rafraîchissement de l'access token

User info Endpoint

https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo

Accès aux ressources protégées

Introspection Endpoint

https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspect

Introspection de l'access token ou du refresh token
Logout Endpoint https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout Dé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 Request)

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
    Authorization: Basic Base64 (client_id:client_secret)

    Exemple:
    Si le Client_ID est "Aladdin" et le secret "open sesame", l'en-tête  HTTP sera la suivante: 
    Content-Type: application/x-www-form-urlencoded
    Authorization : Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  • Paramètres POST:
Paramètre Obligatoire Valeur
scope Oui "openid identity scope_all"

login_hint

Oui Identifiant RPPS de la personne que l'on souhaite authentifier
binding_message Oui Nombre aléatoire à deux chiffres compris entre 00 et 99 (inclus), il doit être généré par le client et transmis au serveur Pro Santé Connect.

Réponse du serveur (accusé de réception)

Paramètre Valeur Description
auth_req_id Jeton 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_in 120

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

interval 5 Le 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

Erreur Description
invalid_request Un paramètre est manquant, une valeur de paramètre est erronée, un paramètre est inclus plusieurs fois ou la requête est mal formée
invalid_scope Le scope demandé est invalide, inconnu ou mal formé
unknown_user_id Les informations transmis par le client au fournisseur d'identité ne permettent pas de connaître l'utilisateur à authentifier.
unauthorized_client Le client n'est pas autorisé à effectuer un appel CIBA
invalid_binding_message Le binding-message passé en paramètre ne correspond pas au format attendu

Récupération du jeton via la méthode Poll (Token Request)

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: TokenEndpoint
  • 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ètre Obligatoire Valeur
grant_type Oui

urn:openid:params:grant-type:ciba

auth_req_id Oui

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 Obligatoire Description
access_token Oui Jeton d'accès à durée limitée
expires_in Oui Valeur entière indiquant le délai d'expiration en secondes de l'access_token 
refresh_token Non Jeton permettant de rafraîchir l'access_token
refresh_expires_in Non Valeur entière indiquant le délai d'expiration en secondes du refresh token
token_type Oui Bearer
id_token Oui Jeton d'identification
scope Non openid, identity,scope_all

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

Messages d'erreur

Les erreurs suivantes peuvent être remontées par le client lourd.  Elles sont spécifiques à CIBA et viennent s'ajouter aux erreurs gérées par OIDC

Code d'erreur Description
authorization_pending La requête d’authentification est en cours de traitement, l'utilisateur n'a pas encore répondu
slow_down La requête d’authentification est en cours de traitement, le client doit respecter l'intervalle de temps défini entre 2 requêtes.
expired_token La transaction auth_req_id a expiré. Le client doit initier une nouvelle demande d’authentification 
access_denied L'utilisateur a refusé la connexion.
unauthorized_client:Invalid client secret le secret utilisé n'est pas le bon pour ce client_ID. 
Invalid_grant, Client not allowed OIDC CIBA Grant Le client_ID/Client_Secret est correct mais n'est pas autorisé à faire du CIBA.
Code erreur 503 - 
HETT retry-after dans le header
Pro Santé Connect est soumis à une forte charge, une nouvelle demande doit être émise en prenant en compte la valeur retournée dans le header

Accès aux ressources protégées, Introspection des jetons, rafraîchissement etc

La différence entre le flux CIBA et le flux "classique" (authorization code flow) porte 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, rafraîchissement des jetons, introspection, ...) 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

Cette page vous a-t-elle été utile ?

Les informations recueillies dans le questionnaire sont enregistrées dans un fichier informatisé par l'ANS afin d’optimiser le site et satisfaire à vos attentes.

Les informations enregistrées sont destinées à l’usage de l’ANS et ne sont rendues accessibles qu’à ses services, personnels, prestataires externes ou partenaires habilités à en prendre connaissance.

Dans le respect de la réglementation applicable en matière de protection des données personnelles, vous disposez notamment d’un droit d’accès, de rectification et d’effacement de vos données.
Vous pouvez exercer ces droits en contactant le délégué à la protection des données de l’ANS, dans les conditions décrites sur la page dédiée Politique de protection des données personnelles du site de l’ANS.