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
Environnement de production
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ètre | Obligatoire | Valeur |
|---|---|---|
| scope | Oui | "openid 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, affiché à l'utilisateur, et transmis à Pro Santé Connect dans ce champ |
| acr_values | Oui | Ce champ doit prendre la valeur "eidas1" |
| requested_expiry | Non | Durée demandée en secondes pour la validité de la demande d'authentification Par défaut, si ce champ n'est pas renseignée, la durée de validité est de 120 secondes |
| channel | Non | Moyen d’authentification demandé :
Par défaut, si ce champ n’est pas renseigné, le moyen d’authentification utilisé sera la e-CPS |
| client_id | Oui (en mTLS) | Le ClientID du service appelant doit être fourni dans les paramètres de la requête POST pour les authentifications par certificat client (mTLS) |
Réponse du serveur
| 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
La liste des erreurs fonctionnelles est la suivante :
| Erreur | Description |
|---|---|
HTTP/1.1 400 Bad Request {"error":"invalid_request", | L'identifiant RPPS fourni dans le paramètre login_hint est inconnu. |
HTTP/1.1 400 Bad Request {"error":"invalid_request", | 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 {"error":"invalid_request", | Le paramètre binding_message n’est pas présent, ou n’a pas le format attendu. |
HTTP/1.1 400 Bad Request {"error":"invalid_request", | Le paramètre channel n'a pas le format attendu. |
La liste, non exhaustive, des erreurs techniques dues à une mauvaise configuration, est la suivante :
| Erreur | Description |
|---|---|
HTTP/1.1 401 Unauthorized {"error":"invalid_client", | Le client_id utilisé pour l'authentification du FS est inconnu. |
HTTP/1.1 401 Unauthorized {"error":"unauthorized_client", | Le client_secret utilisé pour l'authentification du FS n'est pas celui attendu pour ce client_id. |
HTTP/1.1 401 Unauthorized {"error":"invalid_grant", | Le couple client_id/client_secret utilisé est valide, mais ce client_id n'est pas autorisé à faire du CIBA. |
HTTP/1.1 400 Bad Request {"error":"invalid_request", | La demande d'authentification précédente est toujours en cours et n'a pas encore expiré. |
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è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 |
| client_id | Oui (en mTLS) | Le ClientID du service appelant doit être fourni dans les paramètres de la requête POST pour les authentifications par certificat client (mTLS) |
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_token | Jeton d'accès à durée limitée |
| expires_in | Valeur entière indiquant le délai d'expiration en secondes de l'access_token |
| refresh_token | Jeton permettant de rafraîchir l'access_token |
| refresh_expires_in | Valeur entière indiquant le délai d'expiration en secondes du refresh token |
| token_type | Valeur constante : "Bearer" |
| id_token | Jeton d'identification |
| scope | Liste 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 :
| Erreur | Description |
|---|---|
HTTP/1.1 400 Bad Request {"error":"authorization_pending", | La requête d’authentification est en cours, l'utilisateur n'a pas encore répondu. |
HTTP/1.1 400 Bad Request {"error":"access_denied", | L'utilisateur a refusé ou annulé la demande d'authentification. |
HTTP/1.1 400 Bad Request {"error":"slow_down", | 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 {"error":"expired_token", | Le auth_req_id utilisé a expiré, le client doit initier une nouvelle demande d'authentification. |
HTTP/1.1 400 Bad Request {"error":"invalid_grant", | 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 {"error":"invalid_grant", | 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 {"error":"invalid_grant", | 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 :
| Erreur | Description |
|---|---|
HTTP/1.1 401 Unauthorized {"error":"invalid_client", | Le client_id utilisé pour l'authentification du FS est inconnu. |
HTTP/1.1 401 Unauthorized {"error":"unauthorized_client", | Le client_secret utilisé pour l'authentification du FS n'est pas celui attendu pour ce client_id. |
HTTP/1.1 401 Unauthorized {"error":"invalid_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