🔧 Implémentation du protocole OIDC (authorization code flow) pour un Fournisseur de Service

📢 1. Préambule

1.1. Identifiants de tests

Pour tester la configuration de votre Fournisseur de Service tout au long de l'intégration, vous aurez besoin de vous connecter via un Fournisseur d'Identité. Vous trouverez ici les identifiants pour vous connecter au Fournisseur d'Identité de test.

1.2. Valeur de PROCONNECT_DOMAIN

Pour savoir quelles URL appeler au cours de l'authentification, vous aurez besoin de connaître la valeur de PROCONNECT_DOMAIN qui correspond à votre environnement et votre réseau. Vous la trouverez à ce lien.

1.3. Modification des redirect_uri

Si au cours de l'intégration, vous souhaitez changer les redirect_uri de connexion ou de déconnexion configurées par ProConnect, vous pouvez le faire directement sur votre espace. Pour un changement en production, vous pourrez faire la demande en 2 minutes sur ce lien.

1.4. Exemple d'intégration de test

Dépôt Github d'un client ProConnect

📘 2. Mode d'emploi technique

2.1. Intégrer le bouton ProConnect sur votre page de connexion

Quel bouton ProConnect intégrer et comment l'intégrer ?

2.2. Faire pointer le bouton ProConnect vers le authorization_endpoint

Si vous utilisez une bibliothèque agréée, nous vous recommandons de récupérer les URLs via notre Discovery URL : https://PROCONNECT_DOMAIN/api/v2/.well-known/openid-configuration. Cette Discovery URL vous donnera notamment quatre endpoints qui vous serviront par la suite :

• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• end_session_endpoint

Au clic sur le bouton ProConnect :

• générer un state et un nonce aléatoires et stockez-les dans la session du navigateur
• rediriger l'utilisateur vers le authorization_endpoint. Les query parameters à ajouter sont décrits ci-dessous.

Le champ scope et sa différence avec la notion de claims sont expliqués ici. La liste des scopes que pouvez demander est spécifiée ici.

NB: tout paramètre supplémentaire dans l'URL génèrera une erreur Y000400 : Bad Request Exception. Il n'est pas possible d'ajouter d'autres paramètres.

2.3. Implémentation de la route redirect_uri

Il s'agit de la route vers laquelle sera redirigée votre utilisateur dans le navigateur après authentification par le Fournisseur d'Identité.

Les query parameters renvoyés dans l'URL sont décrits ci-dessous.

NB : le code a une durée d'expiration de 30 secondes.

Votre serveur doit alors effectuer plusieurs actions en "back-channel".

2.3.2. Vérification du state

Vérifier que le champ state récupéré en query parameter correspond bien au state généré précédemment et stocké dans la session du navigateur.

2.3.3. Génération du token

Appeler le endpoint token_endpoint avec les paramètres décrits ci-dessous :

{
  'access_token': <ACCESS_TOKEN>,
  'token_type': 'Bearer',
  'expires_in': 60,
  'id_token': <ID_TOKEN>
}

Vous récupérez alors un JSON, qui contient notamment :

• access_token
• id_token.

L'access_token est un Bearer token. Sa durée de validité est de 60 secondes.

2.3.4. Vérification de l'id_token et du nonce

L'id_token est un JWT, signé avec l'algorithme spécifié à ProConnect lors de l'enregistrement du FS (RS256, ES256 ou HS256).

Vérifier que le JWT est bien signé avec cet algorithme.

Une fois décodé, extraire le nonce et vérifier qu'il correspond bien au nonce stocké dans la session du navigateur.

2.3.5. Stockage du id_token

Stocker le id_token dans la session du navigateur. Cette valeur sera utilisée plus tard, lors de la déconnexion auprès du serveur ProConnect.

2.3.6. Récupération des user info

Appeler le endpoint userinfo_endpoint, en ajoutant l'access_token token dans l'en-tête Authorization, comme décrit ci-dessous :

2.3.7. Authentification de l'utilisateur

Le endpoint user_info_endpoint renvoie un JWT, signé avec l'algorithme spécifié à ProConnect lors de l'enregistrement du FS (RS256, ES256 ou HS256).

Vérifier que le JWT est bien signé avec cet algorithme.

Une fois en possession des informations de votre utilisateur, vous pouvez gérer comme vous le souhaitez sa session.

NB: la session ProConnect a une durée de 12 heures.

• si vous souhaitez que vos sessions utilisateurs durent plus de 12 heures, c'est possible : lorsque votre session utilisateur sera expirée de votre côté, alors le clic sur le bouton "S'identifier avec ProConnect" renverra bien vers la mire d'authentification car la session ProConnect se sera terminée avant.
• si vous souhaitez que vos sessions utilisateurs durent moins de 12 heures, si votre utilisateur clique sur "S'identifier avec ProConnect" entre la fin de votre session et la fin de celle de ProConnect, il sera automatiquement reconnecté à votre service. Une option max-age est décrite dans la spec OIDC et permet de gérer ce cas, mais celle-ci n'est pas encore implémentée sur ProConnect.

2.3.8. Le cas du Silent Login

Il est possible, et plus agréable pour l'utilisateur, de faire en sorte que lorsque l'utilisateur arrive sur votre FS, il se connecte immédiatement et automatiquement à votre FS dans le cas où il dispose d'une session ProConnect en cours (par exemple s'il s'est déjà connecté dans la journée via ProConnect à une autre application). Ce parcours et son implémentation sont décrits à cette page.

2.4. Déconnexion de l'utilisateur

Au clic sur votre bouton de déconnexion, effectuer les actions suivantes :

2.4.1. Déconnexion auprès de ProConnect

Récupérer l'id_token stocké dans la session du navigateur. Appeler le endpoint end_session_endpoint avec les paramètres décrits ci-dessous.

GET /api/v2/session/end?id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3MDRlMDI0Mj
I5MDE1ZDJiZDQ3ZjdhNWU1YWIwNWIzNWM4MzM2YWI0MDNjMzgwMjI5ODVmOGNmYWRjODZmZTkxIiwiYW1yIjpbInB3ZCJdLCJ
hdXRoX3RpbWUiOjE2Njg1MzAzMjYsImFjciI6ImVpZGFzMSIsIm5vbmNlIjoiYWZjODFmZGExZmJiNmQzYzg3NmFmNzVjNzM3
YTEzMDdhMWIyOWJhMDg3M2VmYTA1OWU0NTM1ZDEyMmM5ZGI1YSIsImF0X2hhc2giOiJJVEJTV1J2NW1HRmxxTGQ0Sm5nbnRnI
iwiYXVkIjoiNjkyNWZiODE0M2M3NmVkZWQ0NGQzMmI0MGMwY2IxMDA2MDY1ZjdmMDAzZGU1MjcxMmI3ODk4NTcwNGYzOTk1MC
IsImV4cCI6MTY2ODUzMDM4NiwiaWF0IjoxNjY4NTMwMzI2LCJpc3MiOiJodHRwczovL2ZjYS5pbnRlZzAxLmRldi1hZ2VudGN
vbm5lY3QuZnIvYXBpL3YyIn0.hg1n4WJbzZECwz4VldAybXYreEXJ4fxpSWqDs9V4tTk&
state=3b7bd7fb38ccab89864563f17a89c4cb3bd400164ce828b4cfc2cb01ce8ed9da&
post_logout_redirect_uri=https%3A%2F%2Ffsa1v2.integ01.dev-agentconnect.fr%2Flogout-callback HTTP/1.1
Host: fca.integ01.dev-agentconnect.fr

2.4.2. Implémentation de la route post_logout_redirect_uri

Il s'agit de la route vers laquelle sera redirigé votre utilisateur après déconnexion par le Fournisseur d'Identité.

Le query parameter renvoyé dans l'URL est décrit ci-dessous.

GET /logout-callback?state=3b7bd7fb38ccab89864563f17a89c4cb3bd400164ce828b4cfc2cb01ce8ed9da HTTP/1.1
Host: fsa1v2.integ01.dev-agentconnect.fr

2.4.3. Vérification du state

Vérifier que le champ state récupéré en query parameter correspond bien au state généré lors de la connexion et stocké dans la session du navigateur.

2.4.4. Suppression des informations de connexion

Supprimer les informations de connexion stockée dans la session du navigateur