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.

Pro Santé Connect se base sur les standards suivants : 

  • HTTP 1.1 RFC 7230 – 7235 de l’IETF
  • TLS 1.2 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 (sous la forme d'un Json Web Token),
    • un id_token (sous la forme d'un Json Web Token), 
    • un refresh_token (sous la forme d'un Json Web Token) ;
  • 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.

Les endpoints de Pro Santé Connect

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

Liste des endpoints du BAS :
Discoveryhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorizationhttps://wallet.bas.psc.esante.gouv.fr/auth
Tokenhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfohttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Refreshhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
Logouthttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout
Introspectionhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspect
Backchannel Authentication endpointhttps://auth.bas.psc.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/auth

 

Environnement de Production 

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

Liste des endpoints de Production :
Discoveryhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorizationhttps://wallet.esw.esante.gouv.fr/auth
Tokenhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfohttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Refreshhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
Logouthttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout
Introspectionhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token/introspect
Backchannel Authentication endpointhttps://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/ext/ciba/auth

Détails du fonctionnement

UML PSC

 

Authentification mTLS

Contexte

Actuellement seule la présentation d'un couple Client_ID/Client_Secret est nécessaire pour pouvoir communiquer avec les endpoints de Pro Santé Connect. Conformément à la feuille de route 2023-2027 de l'ANS, nous renforçons la sécurité de ces échanges serveur à serveur en demandant la présentation, en plus du couple Client_ID/Client_Secret, d'un certificat d'authentification client TLS afin de s'inscrire dans une stratégie d'authentification mutuelle mTLS.

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

  • certificat de type ORG AUTH_CLI issu de l'IGC-Santé
  • contenant le Client_ID du service appelant dans son CN (champ "Service applicatif" à renseigner sur la plate-forme de commande)
  • en cours de validité
  • non opposé

Le certificat d'authentification client doit être présenté sur tous les endpoints de PSC adressés par le FS, quel que soit le flux utilisé : Code Flow ou CIBA. Il n’y a pas de endpoint dédié au mTLS : les endpoints à adresser sont les mêmes qu’en TLS simple. Le certificat d'authentification client ne remplace pas le Client_Secret : le mTLS vient en plus, pour renforcer la sécurité des appels HTTPS. Le format des appels OIDC reste inchangé, tel que décrit dans la suite de cette documentation.

Planning

L'utilisation du mTLS sera obligatoire sur le BAS de PSC à partir de juin 2024, et sera facultatif en production à cette même date. L’utilisation du mTLS sera obligatoire à terme sur le BAS et sur la production.

  • Avant juin 2024 :
    • Sur le BAS : facultatif (n'hésitez pas à déployer le mTLS sur vos environnements de test dès maintenant afin de vous familiariser avec le process)
    • Sur la production : non disponible
  • Après juin 2024 :
    • Sur le BAS : obligatoire
    • Sur la production : facultatif (passera en obligatoire dans un délai de 6 mois à compter de juin 2024)

Commande du certificat

La commande d'un certificat de l'IGC-Santé s'effectue en se connectant sur la plateforme de commande IGC-Santé à 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 le formulaire F414. La carte de test utilisée doit être nominative.
  • Pour la production : la commande d'une carte CPx (CPA pour un industriel, CPE pour une structure de santé) et son habilitation sont détaillées sur la documentation de l'IGC-Santé.

L’intégration du certificat client et la configuration du mTLS sur votre serveur dépendent de chaque solution : nous vous invitons à consulter la documentation de la solution que vous utilisez. Pour exemple, la documentation Postman inclus un chapitre dédié à cette intégration.

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ètres de query
ParamètreObligatoireValeur
response_typeOui'code'
client_idOui${client id}
redirect_uriOui${callback uri} - Elle doit être strictement identique à la valeur renseignée lors de la création du service
scopeOuiLe scope doit prendre la valeur « openid scope_all »
acr_valuesOuiCe champ doit prendre la valeur « eidas1 »
staterecommandé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
noncerecommandé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
promptoptionnelPar défaut la valeur est positionnée à prompt=none. 
La valeur prompt=login est utilisée pour forcer la ré-authentification de l'utilisateur. Il peut être utilisé conjointement avec max_age.
A noter : si l'authentification a été faite par carte CPx le login est transparent pour l'utilisateur.
max_ageoptionnelSpécifie le temps écoulé autorisé en secondes depuis la dernière fois que l'utilisateur final a été activement authentifié par PSC. Si le temps écoulé est supérieur à la valeur précisée PSC doit ré-authentifier l'utilisateur.

 

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

Paramètres de query
codeCode d’autorisation : code à usage unique permettant d’appeler le service / token
stateValeur envoyée par le FS lors de la demande d'autorisation
iss

Identité de l’émetteur du jeton : URL de l’endpoint de jetons du serveur d’identification.

à venir : sur le BAS prochainement, sur la PROD ultérieurement 

Remarque : 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.

 

 

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ètreObligatoireValeur
grant_typeOui‘authorization_code’
redirect_uriOui${callback uri} - Elle doit être strictement identique à la valeur renseignée lors de la création du service
client_idOui${client id}
client_secretOui${client secret}
codeOuicode 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 :

expHeure d'expiration du jeton au format Epoch.
iatHeure d'émission du jeton ("Issued AT") au format Epoch.
auth_timeHeure de l'authentification au format Epoch. 
jtiIdentifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu.
issIdentité de l’émetteur du jeton.
URL de l’endpoint de jetons du serveur d’identification.
subIdentifiant technique de l’utilisateur final.
typ"Bearer"
azpClientID du service.
nonceChaine 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_stateLa valeur de session.
scopeLes scopes appelés lors de l'authentification.
sidIdentifiant de la session utilisateur.
SubjectNameIDIdentifiant National du professionnel de santé.
preferred_usernameIdentifiant National du professionnel de santé.

 

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

expHeure d'expiration du jeton au format Epoch.
iatHeure d'émission du jeton ("Issued AT") au format Epoch.
auth_timeHeure de l'authentification au format Epoch. 
jtiIdentifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu.
issIdentité de l’émetteur du jeton.
URL de l’endpoint de jetons du serveur d’identification.
audCe 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.
subIdentifiant technique de l’utilisateur final.
typ"ID"
azpClientID du service.
nonceChaine 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_stateLa valeur de session.
at_hashHash de l'access_token.
sidIdentifiant de la session utililisateur.
SubjectNameIDIdentifiant National du professionnel de santé.
preferred_usernameIdentifiant National du professionnel de santé.

 

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

expHeure d'expiration du jeton au format Epoch.
iatHeure d'émission du jeton ("Issued AT") au format Epoch.
jtiIdentifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu.
issIdentité de l’émetteur du jeton.
URL de l’endpoint de jetons du serveur d’identification.
audCe 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.
subIdentifiant technique de l’utilisateur final.
typ"Refresh"
azpClientID du service.
nonceChaine 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_stateLa valeur de session.
scope"openid scope_all"
sidIdentifiant 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ètreObligatoireValeur
grant_typeOui‘refresh_token’
refresh_tokenOui${refresh_token} 
client_idOui${client id}
client_secretOui${client secret}
scopeOuiopenid 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},
}

A quel moment demander un Refresh Token ?

Afin d'offrir l'expérience la plus fluide possible aux utilisateurs de votre service tout en respectant l'exigence EXI PSC 11 du référentiel PSC, sans pour autant multiplier les appels à PSC, nous préconisons de faire appel au token endpoint par exemple lorsque l'utilisateur accède à une nouvelle page ou rubrique de votre service.

Chaque Refresh Token obtenu a une durée de validité de 30 minutes.

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

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

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 :

 
  BASPRODUCTION
Access tokenDurée de validité des tokens avant rafraichissement2 minutes2 minutes
Refresh_tokenDurée de validité du refresh token émis30 minutes30 minutes
Session web maxFI session max : temps maximum avant que la session FI expire automatiquement4 heures4 heures

Les scopes

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
ScopeClaims
openidsub
profile

codeCivilite

given_name

family_name

rpps

SubjectRefPro

SubjectNameID

interop

SubjectOrganization

Mode_Access_raison

Access_regulation_medicale

UITVersion

PalierAuthentification

SubjectRole

PSI_Locale

SubjectNameID

SubjectOrganizationID

referentiel

SubjectNameID

othersIds

scope_alltout le contenu du UserInfo

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.

Problèmes connus

  • Les utilisateurs de Firefox sous Windows et macOS peuvent rencontrer un échec de connexion par carte CPS physique sur les services utilisant Pro Santé Connect, même après l'installation de la Cryptolib CPS.
    Les utilisateurs de l’application e-CPS ne sont pas impactés.
    La configuration du paramètre security.osclientcerts.assume_rsa_pss_support de Firefox à la valeur false résout le problème.
    Vous trouverez une procédure de configuration détaillée dans le document Configuration de Firefox pour les accès à Pro Santé Connect par carte CPS.
  • Les utilisateurs de Safari sous macOS ne peuvent pas se connecter par carte CPS physique sur les services utilisant Pro Santé Connect.
    Les utilisateurs de l’application e-CPS ne sont pas impactés.
    L'utilisation d'un autre navigateur sous macOS (ex.: Chrome) résout le problème.
    Point d'attention : 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).

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.