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
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 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
- 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 et transmis au serveur Pro Santé Connect. |
| acr_values | Oui | Ce champ doit prendre la valeur "eidas1" |
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