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.

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" du provider 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), et un refresh token (une chaîne de caractères en base64) ;
  • Le client fait un appel vers le "userInfo endpoint" du provider avec l'access token reçu, et Pro Santé Connect renvoie les informations de l'internaute au client.

Je veux identifier/authentifier des utilisateurs avec Pro Santé Connect

Afin d’implémenter Pro Santé Connect, il vous faut faire une demande pour obtenir des accès à notre environnement d’intégration.

Ensuite, vous pourrez, après une demande en ce sens, rejoindre l’environnement de production.

Nos endpoints

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

Environnement Intégration Pro Santé Connect

Endpoints Bac à sable
Discovery https://auth.bas.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorization https://wallet.bas.esw.esante.gouv.fr/auth
Token https://auth.bas.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfo https://auth.bas.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Refresh https://auth.bas.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
Logout https://auth.bas.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout

Environnement Production Pro Santé Connect

Endpoints Production
Discovery https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/.well-known/wallet-openid-configuration
Authorization https://wallet.esw.esante.gouv.fr/auth
Token https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
UserInfo https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/userinfo
Refresh https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/token
Logout https://auth.esw.esante.gouv.fr/auth/realms/esante-wallet/protocol/openid-connect/logout

Détails du fonctionnement

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 : PSC
  • Type d'appel : redirection navigateur

Méthode : GET

Requête :

Paramètres de query
response_type 'code'
client_id ${client id}
redirect_uri ${callback uri}
scope Le scope doit prendre la valeur « openid scope_all »
state 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 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
acr_values Ce champ est nécessaire et doit prendre la valeur « eidas2 »

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
code Code d’autorisation : code à usage unique permettant d’appeler le service / token
state Valeur envoyée par le FS

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 : 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 et un id token.

  • Origine : FS
  • Cible : PSC

Méthode : POST

Requête :

grant-type ‘authorization_code’
redirect_uri ${callback uri}
client_id ${client id}
client_secret ${client secret}
code 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}
}

Avec pour ${id_token} : 

sub Identifiant de l’utilisateur final
preferred_username Identifiant National du professionnel de santé
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.
exp 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.
iat 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.
jti Identifiant unique du jeton permettant de révoquer le jeton et empêcher le rejeu.
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.

UserInfo

Contexte : Le FS a récupéré un access token. Il veut maintenant récupérer les User Info.

  • Origine : FS
  • Cible : PSC

Méthode : GET

Header http: Authorization = 'Bearer ${access_token}'

Données Usager

Le scope openid scope_all est obligatoire. Il permet de récupérer les données de l'utilisateur final.

scope_all est actuellement le seul scope existant sur Pro Santé Connect. Si un Fournisseur de service envoie une valeur de scope autre que scope_all, Pro Sante Connect retournera un message d'erreur.

Données Utilisateur
Champ Description
family_name Nom d'exercice
given_name Prénom
sub Identifiant du sujet authentifié
iss Identité de l’émetteur du jeton.
URL de l’endpoint d’informations utilisateur du serveur d’identification.
aud Ce champ contient la liste des identifiants des systèmes cibles pour lesquels le jeton a été délivré. La liste doit contenir au moins une entrée. Doit contenir parmi ses valeurs le champ OAuth 2.0 client_id du système cible.
SubjectNameID Identifiant National du professionnel de santé
SubjectRefPro Liste des données du Référentiel Professionnel du PS identifié
Voir des exemples pour le champs SubjectRefPro, pour différents types d'utilisateurs
Voir le mapping Données UserInfo & correspondance avec le MOS
UITVersion Version du jeton utilisée. « 1.0 »
Palier_authentification « APPPRIP3^1.2.250.1.213.1.5.1.1.1 » pour le palier 3 de l'authentification privée des acteurs sanitaires, médico-sociaux et sociaux personnes physiques.
« APPPRIP2^1.2.250.1.213.1.5.1.1.1 » pour le palier 2 de l'authentification privée des acteurs sanitaires, médico-sociaux et sociaux personnes physiques.
« APPPRIP1^1.2.250.1.213.1.5.1.1.1 » pour le palier 1 de l'authentification privée des acteurs sanitaires, médico-sociaux et sociaux personnes physiques.
PSI_Locale 1.2.250.1.213.1.3.1.1
SubjectRole contient le « [Code SubjectRole]^1.2.250.1.213.1.1.5.5» avec Code SubjectRole de la ligne sélectionnée par le PS parmi les données de SubjectRefPro.
Sinon, contient la valeur correspondante d’une ligne des données de SubjectRefPro.
Secteur_Activite contient le « [Code Secteur_Activite]^1.2.250.1.71.4.2.4» avec Code Secteur_Activite de la ligne sélectionnée par le PS parmi les données de SubjectRefPro.
Sinon, contient la valeur correspondante d’une ligne des données de SubjectRefPro.
SubjectOrganization contient le nom ou description de la personne morale, structure d’exercice de la ligne sélectionnée par le PS parmi les données de SubjectRefPro.
Sinon, contient la valeur correspondante d’une ligne des données de SubjectRefPro.
SubjectOrganizationID contient l’identifiant de la personne morale, structure d’exercice de la ligne sélectionnée par le PS parmi les données de SubjectRefPro.
Sinon, contient la valeur correspondante d’une ligne des données de SubjectRefPro.
Acces_Regulation_Medicale VRAI si accès pour régulation médicale (exemple : Urgentiste).
Sinon FAUX par défaut.
Mode_Acces_Raison si Acces_Regulation_Medicale est VRAI, contient un commentaire.
Sinon « » par défaut.
otherIDs Contient la table de correspondance des identifiants du PS (sous forme de liste), chaque identifiant est composé de 3 attributs : identifiant, origine, qualité (voir quelques exemples). Cette information sera mise à disposition au moment de la bascule ADELI-RPPS des infirmiers.

Utiliser les niveaux eIDAS en tant que FS

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.

Je veux déconnecter l'utilisateur de PRO Santé Connect

La déconnexion est en cours de spécification dans la norme OpenID Connect, et en cours d'implémentation dans Pro Santé Connect.

La déconnexion dans Pro Santé Connect comporte actuellement certaines restrictions, que vous retrouverez détaillées dans la FAQ.

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. Pour se faire, Pro Santé Connect passe par le mécanisme de retour d'erreurs d'un fournisseur d'identité openid connect tel que décrit dans la norme (https://openid.net/specs/openid-connect-core-1_0.html#AuthError)

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 :

Durée de vie des données
Access token Durée de validité des tokens avant rafraichissement 2 minutes
Session web FI session idle : temps d'inactivité après lequel la session expire 15 minutes
Session web max FI session max : temps maximum avant que la session FI expire automatiquement 4 heures

Bascule ADELIP-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.

Cette information sera mise à disposition au moment de la bascule ADELI-RPPS des infirmiers.

Pour plus d'informations concernant la Bascule ADELI-RPPS vous pouvez consultez la page dédiée