Prérequis
Afin d’implémenter PRO Santé Connect, il vous faut faire une demande pour obtenir des accès à notre environnement d’intégration. Vous pouvez faire cette demande depuis la rubrique "Mon Compte"
Concepts de base : le protocole OpenID Connect
Introduction
Le protocole OpenID Connect (OIDC) est au cœur du fonctionnement de Pro Santé Connect. C'est une surcouche d'identification au protocole OAuth 2.0.
Les parties prenantes dans le contexte OIDC sont :
- Les clients: applications qui délèguent l'authentification. On verra aussi parfois le terme de Relying Parties (RP) ou de fournisseurs de service (FS). Dans notre contexte, il s'agit de services numériques du secteur de la santé. Ils doivent implémenter le standard OpenId Connect en tant que client ;.
- Les utilisateurs finaux : pour Pro Santé Connect, il s'agit donc des professionnels de santé ;
- Le fournisseur d'identité : acteur qui effectue l'authentification et fournit les données d'identité aux clients. On verra également le terme Identity Provider.
En résumé, les clients s'appuient sur un fournisseur d'identité pour authentifier des utilisateurs finaux.
- 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
- Vous pouvez suivre nos travaux au sein de la communauté OpenID concernant l'interface OpenID CIBA.
PRO Santé Connect se base sur les standards suivants :
- HTTP 1.1 RFC 7230 – 7235 de l’IETF
- TLS 1.2 (ou supérieur) RFC 5246 de l’IETF
- JSON RFC 7159 de l’IETF
- OpenID Connect 1.0 (OIDC 1.0) de l’OIDF (OpenID Foundation)
- OAuth 2.0 RFC 6749 et RFC 6750 de l’IETF
- JWT (JSON Web Token) RFC 7519, JWS RFC 7515, JWE RFC 7516, JWA RFC 7518 de l’IETF
Les standards suivants ne sont pas appliqués :
- FHIR STU3 Security labels d’HL7
- HEART Profile for OAuth 2.0, HEART Profile for OpenID Connect 1.0 de l’OIDF
Il est à noter que :
- L’entête HTTP Category n’est pas utilisé au sein de PRO santé Connect (voir ci-dessus : standards non appliqués).
- Les échanges applicatifs de données structurées se font uniquement au format JSON.
- Les jetons (identification et information) ont bien un chiffrement asymétrique avec une clé RSA 2048. L’algorithme de chiffrement est du RSA SHA-256.
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 de PRO Santé Connect. Il lui fournit une URL de redirection (l'URL du client vers lequel l'internaute est redirigé une fois authentifié), aussi appelée "callback endpoint". En retour PRO Santé Connect donne au client un client ID et un client secret.
Lorsque le professionnel de santé clique sur le bouton d'authentification du client, le flux est le suivant :
- Le client fait une redirection vers le "authorization endpoint" de Pro Santé Connect avec son client id et son url de redirection. Pro Santé Connect redirige alors le professionnel de santé vers sa mire d'authentification. Si l'internaute se loggue correctement, Pro Santé Connect renvoie un code d'autorisation au client ;
- Le client fait un appel vers le "token endpoint" de Pro Santé Connect avec le code d'autorisation reçu, et authentifie cette requête avec son client id et son client secret. Pro Santé Connect 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),
- un refresh_token (une chaîne de caractères en base64) ;
- Le client fait un appel vers le "userInfo endpoint" avec l'access_token reçu, et Pro Santé Connect renvoie les informations de l'internaute au client.
Accès en 1 clic
Les endpoints de PRO Santé Connect
Nous utilisons les endpoints tels que définit par le standard OpenID.
Environnement Intégration - Bac à sable
Environnement de Production
Détails du fonctionnement
Détail des flux
Autorisation
Contexte : Le FS redirige depuis la requête précédente vers le Endpoint d'autorisation pour engager la cinématique d'authentification.
- Origine : FS
- Cible : Authorization Endpoint
- Type d'appel : redirection navigateur
Méthode : GET
Requête :
| Paramètre | Obligatoire | Valeur |
|---|---|---|
| response_type | Oui | 'code' |
| client_id | Oui | ${client id} |
| redirect_uri | Oui | ${callback uri} - Elle doit être strictement identique à la valeur renseignée lors de la création du service |
| scope | Oui | Le scope doit prendre la valeur « openid scope_all » |
| acr_values | Oui | Ce champ doit prendre la valeur « eidas1 » |
| state | recommandé | Valeur générée aléatoirement par le FS, renvoyée telle quelle dans l'url de callback pour être vérifiée par le FS. Il permet de se prémunir contre les attaques CSRF |
| nonce | recommandé | Valeur générée aléatoirement par le FS, recopié dans le token d'authentification pour être vérifié par le FS. Il permet de se prémunir contre les attaques de rejeu |
Réponse : Une fois l’authentification terminée, le FI redirige l’utilisateur vers la callback uri avec en paramètre de query :
| code | Code d’autorisation : code à usage unique permettant d’appeler le service / token |
|---|---|
| state | Valeur envoyée par le FS lors de la demande d'autorisation |
La redirection
Contexte : L'internaute s'est identifié sur le FI, Pro Santé Connect redirige vers le callback du FS, avec un Authorization code dans l'URL.
- Origine : PSC
- Cible : URL de redirection du FS
- Type d'appel : redirection navigateur
Méthode : GET
Le token
Token
Contexte : Le FS a récupéré un Authorization code. Il veut maintenant récupérer un access token, un id_token et un refresh_token
- Origine : FS
- Cible : Token Endpoint
Méthode : POST
Requête :
| Paramètre | Obligatoire | Valeur |
|---|---|---|
| grant_type | Oui | ‘authorization_code’ |
| redirect_uri | Oui | ${callback uri} - Elle doit être strictement identique à la valeur renseignée lors de la création du service |
| client_id | Oui | ${client id} |
| client_secret | Oui | ${client secret} |
| code | Oui | code récupéré en query param dans l'uri de callback |
Réponse : JSON
{
'access_token': ${access_token},
'token_type': 'Bearer',
'refresh_token': ${refresh_token},
'expires_in': ${expiration},
'id_token': ${id_token}
}
La valeur ${access_token} est structurée de la manière suivante :
| exp | Heure d'expiration du jeton au format Epoch |
|---|---|
| iat | Heure d'émission du jeton ("Issued AT") au format Epoch. |
| auth_time | Heure de l'authentification au format Epoch. |
| jti | Identifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu. |
| iss | Identité de l’émetteur du jeton. URL de l’endpoint de jetons du serveur d’identification. |
| sub | Identifiant technique de l’utilisateur final |
| typ | "Bearer" |
| azp | nom du service |
| nonce | Chaine de caractère associant la session du système cible à l’ID token. Contient la valeur du nonce de la requête d’authentification du système cible. Le « nonce » est nécessaire afin d’éviter les attaques par rejeu. |
| session_state | la valeur de session |
| acr | "eidas1" |
| scope | "openid scope_all" |
| sid | Identifiant de la session utililisateur. |
| preferred_username | Identifiant National du professionnel de santé |
La valeur ${id_token} est structurée de la manière suivante:
| exp | Heure d'expiration du jeton au format Epoch |
|---|---|
| iat | Heure d'émission du jeton ("Issued AT") au format Epoch. |
| auth_time | Heure de l'authentification au format Epoch. |
| jti | Identifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu. |
| iss | Identité de l’émetteur du jeton. URL de l’endpoint de jetons du serveur d’identification. |
| aud | Ce champ contient la liste des identifiants des systèmes cibles pour lesquels le jeton a été fourni. La liste doit contenir au moins une entrée. Il doit compter parmi ses valeurs la valeur du champ OAuth 2.0 client_id du système cible. |
| sub | Identifiant technique de l’utilisateur final |
| typ | "ID" |
| azp | nom du service |
| nonce | Chaine de caractère associant la session du système cible à l’ID token. Contient la valeur du nonce de la requête d’authentification du système cible. Le « nonce » est nécessaire afin d’éviter les attaques par rejeu. |
| session_state | la valeur de session |
| acr | "eidas1" |
| sid | Identifiant de la session utililisateur. |
| subjectnameID | Identifiant professionnel de santé |
| preferred_username | Identifiant National du professionnel de santé |
La valeur ${refresh_token} est structurée de la manière suivante:
| exp | Heure d'expiration du jeton au format Epoch |
|---|---|
| iat | Heure d'émission du jeton ("Issued AT") au format Epoch. |
| jti | Identifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu. |
| iss | Identité de l’émetteur du jeton. URL de l’endpoint de jetons du serveur d’identification. |
| aud | Ce champ contient la liste des identifiants des systèmes cibles pour lesquels le jeton a été fourni. La liste doit contenir au moins une entrée. Il doit compter parmi ses valeurs la valeur du champ OAuth 2.0 client_id du système cible. |
| sub | Identifiant technique de l’utilisateur final |
| typ | "Refresh" |
| azp | nom du service |
| nonce | Chaine de caractère associant la session du système cible à l’ID token. Contient la valeur du nonce de la requête d’authentification du système cible. Le « nonce » est nécessaire afin d’éviter les attaques par rejeu. |
| session_state | la valeur de session |
| scope | "openid scope_all" |
| sid | Identifiant de la session utililisateur. |
UserInfo
Contexte : Le FS a récupéré un access token. Il veut maintenant récupérer les User Info.
- Origine : FS
- Cible : UserInfo Endpoint
Méthode : GET
Header http: Authorization = 'Bearer ${access_token}'
Vous pouvez trouver plus d'informations sur les données sectorielles et la structure du jeton sur la page dédiée de UserInfo.
RefreshToken
Contexte : Le FS souhaite rafraîchir un jeton en utilisant le refresh_token
- Origine : FS
- Cible : Token Endpoint
Méthode : POST
- Body Content-type : application/x-www-form-urlencoded
| Paramètre | Obligatoire | Valeur |
|---|---|---|
| grant_type | Oui | ‘refresh_token’ |
| refresh_token | Oui | ${refresh_token} |
| client_id | Oui | ${client id} |
| client_secret | Oui | ${client secret} |
| scope | Oui | openid scope_all |
En cas de succès le serveur renvoie une réponse HTTP 200.
Réponse : JSON
{
'access_token': ${access_token},
'token_type': 'Bearer',
'refresh_token': ${refresh_token},
'expires_in': ${expiration},
}
eIDAS
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.
Comme la norme ne prévoit pas aujourd'hui de mesures techniques particulières pour préciser le niveau souhaité, Pro Santé Connect utilise le claim optionnel "acr" (https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters) de la norme OpenID Connect. Pour le FS, cela veut dire remplir acr_values lors de la demande d'authentification.
Au sujet de acr_values, on notera que c'est, selon la norme, un "voluntary claim" qui théoriquement traduit une préférence et non une exigence. Cependant, ce champ est nécessaire à l'utilisation de PRO Santé Connect.
La déconnexion de l'utilisateur
La déconnexion est en cours de spécification dans la norme OpenID Connect. PRO Santé Connect ne prend pas en charge tous les cas possibles, vous pouvez vous référer à la documentation liée à la déconnexion pour en savoir plus.
La déconnexion dans Pro Santé Connect comporte actuellement certaines restrictions, que vous retrouverez détaillées dans la FAQ.
CIBA
CIBA est une fonctionnalité OpenID en cours d'implémentation dans PRO Santé Connect.
Vous pouvez trouver la documentation liée sur la page dédiée à CIBA
L'introspection
L’introspection permet à un fournisseur de service de valider un jeton auprès du serveur d’authentification de ProSantéConnect.
Vous pouvez trouver la documentation liée sur la page dédiée à l'introspection
Les données de Pro Santé Connect qui expirent
Pro Santé Connect gère plusieurs types de données "périssables" lors du déroulé d'une authentification par OpenID Connect. Chacune de ces données possède une durée de vie qui lui est propre au delà de laquelle elle doit être régénérée. En voici le détail :
| BAS | PRODUCTION | ||
| Access token | Durée de validité des tokens avant rafraichissement | 2 minute | 2 minutes |
| Refresh_token | Durée de validité du refresh token émis | 30 minutes | 3 minutes |
| Session web max | FI session max : temps maximum avant que la session FI expire automatiquement | 4 heures | 4 heures |
Bascule ADELI-RPPS des infirmiers
Une nouvelle fonctionnalité permet à PSC de fusionner les identités de PS ayant plusieurs identifiants différents (jeton étendu).
- Cette information est présente dans "userinfo", dans un nouveau champs "otherIds"
- Ce champs est composé d'une liste d'identifiants
- Chaque identifiant contient 3 attributs : identifiant, origine, qualité (voir quelques exemples)
Le champ "SubjectNameID" étant l'identifiant d'authentification, les informations présentes dans "otherIds" permettent aux FS de faire la correspondance avec un identifiant de compte dans leur SI pouvant être différent de l'identifiant avec lequel le PS s'est authentifié à PSC (présent dans le champ "SubjectNameID").
Le jeton "étendu" est totalement identique et compatible avec le jeton actuel, avec le champ "otherIds" en plus.
Pour plus d'informations concernant la Bascule ADELI-RPPS vous pouvez consultez la page dédiée
Gestion d'erreurs entre Pro Santé Connect et le FS
En tant qu'OpenID Connect provider, Pro Santé Connect peut renvoyer toutes sortes d'erreurs à une application cliente.
Vous pouvez trouver la documentation liée sur la page dédiée à la gestion des erreurs.