Documentation technique

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

Nous utilisons les endpoints tels que définit par le standard OpenID.

Environnement Intégration - Bac à sable

Portail e-CPS BAS : https://wallet.bas.psc.esante.gouv.fr

Environnement de Production 

Portail e-CPS : https://wallet.esw.esante.gouv.fr

Contexte

Jusqu’à présent, les FS disposaient d’une seule méthode pour s’authentifier auprès de PSC : "client_secret_post" (authentification par Client_ID et Client_Secret).

Désormais, conformément à la feuille de route 2023-2027 de l'ANS et afin de renforcer la sécurité des échanges serveur à serveur, Pro Santé Connect s’inscrit dans une stratégie d'authentification mutuelle mTLS et propose une seconde méthode d’authentification : "tls_client_auth" (authentification par Client_ID et certificat client X.509).

Dans un premier temps, seuls les FS candidats à l’Espace de Confiance (EDC) PSC sont tenus de mettre en œuvre cette nouvelle méthode d’authentification "tls_client_auth". Les FS de la Communauté PSC (le niveau actuel, correspondant au référentiel Pro Santé Connect publié dans l’arrêté du 24 avril 2024) peuvent choisir de conserver la méthode "client_secret_post", ou d’implémenter la nouvelle méthode "tls_client_auth".

Planning

La méthode d’authentification mTLS est disponible depuis :

• Sur le BAS : 05 Novembre 2024
• Sur la production : 18 février 2025

Les formulaires de demande d’accès pour la gestion de vos services PSC (accès réservé aux Responsables techniques des services depuis leur compte iSC) sont en cours d'évolution pour permettre à terme :

1. de déclarer la méthode d’authentification choisie (*) : Client_Secret ou mTLS
2. de déclarer l'espace (Communautaire ou EDC) que votre service souhaite intégrer

(*) La méthode d'authentification configurée pour un ClientID donné est unique : soit Client_Secret, soit mTLS.

Demande d'accès mTLS / EDC

Le planning de cette évolution des formulaires pouvant être décalé par rapport à la mise à disposition du mTLS et de l'EDC, nous vous invitons actuellement à suivre le processus suivant pour renseigner le formulaire de demande d'accès :

1. réaliser vos demandes sur l'Espace Communautaire uniquement
2. utiliser le champ « Commentaire(s) » du formulaire de demande de création ou modification pour signaler le choix :
   1. de l’authentification mTLS (hors EDC). Vous avez dans ce cas la possibilité :
      1. de conserver votre clientID existant, via une demande de modification
      2. de demander un second ClientID configuré en mTLS pour le même numéro d'habilitation Datapass, via une demande de création
   2. de l'authentification mTLS au sein de l'EDC, en précisant votre Numéro de Référencement Unique (NRU). Vous obtiendrez ainsi un clientID spécifique dédié à l'EDC :
      1. l'accès à l'Espace de Confiance s'effectue obligatoirement via une demande de création
      2. si vous possédiez déjà un clientID pour votre service, la demande de création s'effectue sur le même numéro d'habilitation Datapass
3. transmettre le DN (Distinguished Name) de votre certificat via la demande de Transmission mTLS du formulaire de demande d'accès, suite à la réception de votre ClientID. Le support Pro Santé Connect revient vers vous une fois la configuration de votre accès finalisée avec ce DN, pour vous signifier la disponibilité de votre accès.

Commande du certificat 

Le certificat d'authentification client demandé présente les caractéristiques suivantes :

• Certificat X.509 de type ORG AUTH_CLI issu de l'IGC-Santé
• Le Client_ID du service appelant est présent dans le CN (champ "Service applicatif" à renseigner sur la plate-forme de commande PFCNG)
• En cours de validité
• Non opposé

La commande d'un certificat de l'IGC-Santé s'effectue en se connectant sur la plateforme de commande PFCNG à l’aide d’une carte CPx préalablement habilitée. Un lecteur de cartes PC/SC, à se procurer dans le commerce, est nécessaire pour cette connexion. Au moment de la commande de votre certificat ORG AUTH_CLI sur cette plateforme, le Client_ID de votre service doit être renseigné dans le champ "Service applicatif".

• Pour le BAS : la commande d'une carte CPx de test et son habilitation s'effectuent depuis la démarche F414. La carte de test utilisée doit être nominative.
• Pour la production : la commande d'une carte CPx (CPA pour un industriel, CPE nominative pour une structure de santé) et son habilitation sont détaillées sur la documentation de l'IGC-Santé.

Vous pouvez consulter notre webinaire dédié au retrait d’un certificat sur la PFCNG pour plus d’informations.

Configuration du client OpenID Connect

L’intégration du certificat client et la configuration de l’authentification mTLS sur votre client OpenID Connect dépendent de chaque solution : nous vous invitons à consulter la documentation de la solution que vous utilisez. Pour exemples :

• la documentation Postman inclut un chapitre dédié à cette intégration
• le guide Configuration TLS de Keycloak fournit des cas d'usage pratiques pour la configuration du mTLS dans cet outil (en complément de la documentation Keycloak officielle) 

Conformément aux standards Oauth 2.0 et OIDC, les FS utilisant la méthode d’authentification "tls_client_auth" doivent présenter leur certificat client sur les endpoints suivants :

• Token Endoint
• Introspection Endpoint
• Revocation Endpoint
• Backchannel Authentication Endpoint (flux CIBA uniquement)

La méthode d’authentification sur ces endpoints doit être adaptée pour "tls_client_auth", avec la présentation du certificat client X.509 pour établir la session mTLS avec PSC, en lieu et place de la fourniture du Client_Secret.

Le format des appels OIDC reste inchangé, tel que décrit dans la suite de cette documentation.

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 :

Réponse : Une fois l’authentification terminée, le FI redirige l’utilisateur vers la callback uri avec en paramètre de query :

Remarques, pour des raisons de sécurité :

• Le mécanisme CORS n'est pas autorisé avec Pro Santé Connect

En effet, ce mécanisme permet l’authentification entre le navigateur client et les services PSC ce qui implique de passer dans la requête d’autorisation le client_id et le client_secret, ce qui est contraire à l’exigence 22 : « Le fournisseur de service DOIT conserver le client ID et le Secret au niveau d’un serveur ».
Vous pouvez retrouver ici les exigences complètes de Pro Santé Connect.

• L'utilisation de Pro Santé Connect dans une iframe n'est pas autorisée

Pro Santé Connect suit en cela les recommandations établies par l'ANSSI, en particulier au niveau de la stratégie Content Security Policy mise en oeuvre.

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

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 :

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 :

La valeur ${id_token} est structurée de la manière suivante:

La valeur ${refresh_token} est structurée de la manière suivante:

Remarque : Depuis Keycloak 25 (déployé sur le BAS le 25/09/2024 et sur la Production le 06/11/2024) l'attribut session_state n'est plus présent dans le jeton refresh_token. En raison des évolutions régulières apportées à Keycloak, nous ne sommes pas en mesure de garantir la pérennité de l'attribut session_state dans les autres jetons. Si votre service nécessite d'obtenir la valeur de cet attribut, nous vous préconisons de la récupérer dans l'attribut sid, qui contient la même valeur et qui est présent dans les trois jetons retournés par le token endpoint.
 

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.

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

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 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 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 est une fonctionnalité OpenID implémentée dans Pro Santé Connect depuis juin 2022.
Vous pouvez trouver la documentation liée sur la page dédiée à CIBA

L’introspection permet à un fournisseur de service  de valider un jeton auprès du serveur d’authentification  de Pro Santé Connect. 

Vous pouvez trouver la documentation liée sur la page dédiée à l'introspection

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. Le détail de ces durées de vie est fourni dans le tableau ci-dessous.

Une session PSC s'applique de manière globale à un utilisateur donné, indépendamment du ou des services sur lesquels il s'est authentifié avec PSC.

En flux Code Flow, PSC implémente un mécanisme de SSO au sein du navigateur web : chaque service sur lequel l'utilisateur s'authentifie avec PSC bénéficie de ce partage de session au sein du même navigateur. Cela signifie que l'utilisateur s'étant authentifié avec PSC sur un premier service, se verra automatiquement authentifié s'il demande l'accès à un second service avec PSC, dans la limite des durées précisées ci-dessous. L'exigence de rafraichissement de la session PSC par chaque service (EXI PSC 11 du Référentiel PSC) a ainsi pour but d'offrir une expérience satisfaisante à l'utilisateur, lui permettant de bénéficier de ce partage de session tant qu'il reste actif sur au moins l'un des services raccordés à PSC qu'il utilise. En flux CIBA, un mécanisme de SSO est également à l'étude.

Une session PSC débute lors de la première authentification de l'utilisateur. S'il n'y a pas d'activité maintenue sur cette session, elle expire 30 minutes plus tard. En cas d'activité sur la session (nouvelle demande d'authentification ou demande de rafraichissement), sa durée est prolongée de 30 minutes supplémentaires. Jusqu'à une durée maximum de 4 heures, où la session expire automatiquement dans tous les cas. Si une déconnexion (appel au logout endpoint) est demandée par l'un des services, la session PSC se termine immédiatement pour l'utilisateur concerné. L'utilisation du paramètre 'max_age' par l'un des services peut modifier la durée de la session PSC sans activité (30 minutes par défaut).

Pro Santé Connect met à disposition différents scopes. 

• Il est possible de récupérer un groupe de données spécifiques en utilisant le scope adapté
• Il est possible de combiner plusieurs scopes

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

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.

• En usage full mobile (authentification et utilisation du service sur le téléphone mobile), les utilisateurs disposant d'un appareil sous Android 15 ou plus peuvent rencontrer le message "Authentification échouée" dans l'application e-CPS. Un réglage au niveau du navigateur ou de l'application utilisée pour accéder au service va résoudre le problème : autoriser l'utilisation de la batterie en arrière plan sans restriction. La configuration de ce réglage est détaillée dans le guide Je rencontre un problème avec ma e-CPS.
• Sous macOS, la connexion par carte CPS physique dans un navigateur autre que Firefox nécessite l'installation préalable de CPS-Gestion depuis le Mac App Store
• La présence d'un antivirus qui sécurise les connexions SSL (https) peut empêcher la connexion par carte CPS physique sur les services en ligne. Pour contourner ce problème, il est généralement possible d'ajouter les URL de ces services en ligne dans les exceptions de l'antivirus : vous référer pour cela à la documentation proposée par l'éditeur de votre antivirus.
• Du fait d'une limitation constatée dans le traitement interne du module mod_auth_openidc, l'intégration de Pro Santé Connect dans un serveur Apache via ce module peut nécessiter de configurer le paramètre OIDCPassUserInfoAs à la valeur "json" pour récupérer le contenu du champ otherIds du jeton UserInfo retourné par PSC (la valeur par défaut "claims" ne permettant pas de transmettre le contenu de ce champ à l'applicatif via les headers).