Gestion des erreurs
Dans le cadre de son rôle de identity provider OpenID Connect, FranceConnect (et FranceConnect+) peut être amené à retourner des erreurs aux fournisseurs de services intégrés, conformément à la spécification OpenID Connect Core 1.0, en particulier les sections 3.1.2.6 (authentification), 3.1.3.4 (jeton d'accès), 5.3.3 (service d'informations utilisateur). Ces erreurs peuvent survenir à différentes étapes du parcours d’authentification, et leur gestion correcte est essentielle à plusieurs titres :
- Garantir une expérience utilisateur cohérente et sécurisée, y compris en cas d’échec ;
- Faciliter la remontée et le diagnostic des anomalies côté fournisseur de service ;
- Contribuer à la conformité technique vis-à-vis des standards de FranceConnect et du protocole OpenID Connect.
Cette section présente les principaux cas de retours d’erreurs susceptibles d’être rencontrés, ainsi que les mécanismes normés de communication mis en œuvre par FranceConnect.
Cas typiques de retour d’erreur #
FranceConnect peut retourner une erreur dans les situations suivantes :
- Requête invalide : la requête transmise par le fournisseur de service ne respecte pas les exigences de la spécification (ex. : paramètres absents, incorrects ou incohérents).
- Erreur technique : un dysfonctionnement interne empêche FranceConnect de traiter la requête (erreur temporaire, indisponibilité d’un composant, etc.).
- Interruption par l’usager : l’utilisateur choisit de ne pas poursuivre son authentification (ex. : retour volontaire à l’écran précédent, fermeture du navigateur, refus explicite).
- Échec d’identification : les données fournies par le fournisseur d’identité ne permettent pas d’identifier de manière certaine ou légitime la personne. Cela peut notamment se produire dans les cas suivants : utilisateur non présent dans le Répertoire National d’Identification des Personnes Physiques (RNIPP), homonymie parfaite rendant l’identification incertaine, utilisateur identifié comme décédé, etc.
Mécanisme de retour d’erreur #
Lorsqu'une erreur est détectée, FranceConnect applique les mécanismes prévus par la spécification OpenID Connect pour notifier l’erreur à l’application cliente. Cette notification prend la forme d’une redirection de l’utilisateur vers l’URL de redirection (redirect_uri) fournie par le fournisseur de service lors de l’appel initial au point d’entrée /authorize.
| Paramètre | Description |
|---|---|
| error | code d'erreur identifiant l'erreur |
| error_description | description de l'erreur |
| state | valeur du state passée lors de la requête /authorize |
Rappel important : toute décision métier ou tout affichage conditionnel doit être fondé exclusivement sur la valeur du paramètre error. Le champ error_description ne doit être utilisé que pour enrichir les journaux techniques ou les rapports de diagnostic.
Exemple de retour en cas d’erreur #
HTTP/1.1 302 Found
Location: https://client.example.org/cb?
error=invalid_request
&error_description=Unsupported%20response_type%20value
&state=af0ifjsldkjLes codes d'erreur possibles #
Les erreurs que peuvent renvoyer FranceConnect ou FranceConnect+ sont les suivantes :
Ce code d'erreur est renvoyé lorsque les données demandées dans la requête /authorize au travers des scopes ne sont pas autorisées. Ce problème intervient généralement pendant la phase de développement, lors de la mise en production ou la mise à jour de la fonctionnalité de connexion via FranceConnect ou FranceConnect+ dans votre service.
Qu'indiquer à l'usager ?
Lorsqu'un usager rencontre ce type d'erreur, il ne pourra pas s'authentifier à votre service via FranceConnect ou FranceConnect+. Il est recommandé de rediriger l'usager vers la page de connexion de votre service en indiquant qu'il n'a pas été possible de se connecter et qu'il doit choisir un autre mode de connexion.
Que faire pour corriger le problème ?
Si ce problème se produit pour un usager, il est problable que ce problème se reproduise pour l'ensemble de vos usagers. L'accès à votre service via FranceConnect ou FranceConnect+ est alors impossible.
Pour corriger ce problème, il est nécessaire dans un premier temps de retirer les scopes pour lesquels vous n'avez pas l'autorisation. Si vous avez absolument besoin d'accéder à des informations dont vous n'avez pas l'autorisation, il est nécessaire de mettre à jour votre demande d'habilitation pour obtenir l'autorisation d'accéder à ces données et de pouvoir ainsi demander les scopes correspondants.
Ce code d'erreur indique que la requête /authorize n'est pas correcte et qu'elle ne peut être traitée par FranceConnect ou FranceConnect+. Cette erreur se produit généralement lors de la phase de développement.
Qu'indiquer à l'usager ?
Lorsqu'un usager rencontre ce type d'erreur, il ne pourra pas s'authentifier à votre service via FranceConnect ou FranceConnect+. Il est recommandé de rediriger l'usager vers la page de connexion de votre service en indiquant qu'il n'a pas été possible de se connecter et qu'il doit choisir un autre mode de connexion.
Que faire pour corriger le problème ?
Si ce problème se produit pour un usager, il est problable que ce problème se reproduise pour l'ensemble de vos usagers. L'accès à votre service via FranceConnect ou FranceConnect+ est alors impossible.
Pour corriger le problème, il convient de modifier vos développements pour que la requête /authorize fonctionne. Pour cela, vous pouvez consulter cette documentation pour comprendre les points qui seraient mal implémentés.
Ce code d'erreur indique que l'utilisateur n'a pas pu réaliser son authentification. Cela peut être dû à plusieurs raisons mais qui concernent forcément l'utilisateur :
- l'utilisateur a souhaité revenir en arrière en arrivant sur FranceConnect ou FranceConnect+ ;
- l'utilisateur n'a pas réussi à s'authentifier chez le fournisseur d'identité ;
- les contrôles réalisés par FranceConnect auprès du RNIPP ne permettent pas de laisser l'utilisateur continuer son authentification. C'est le cas par exemple :
- si l'utilisateur n'est pas référencé dans le RNIPP ;
- s'il existe des homonymies parfaites dans le RNIPP sur l'ensemble des données de l'identité pivot ;
- si l'utilisateur est décédé ;
- si des données d'identité obligatoires de l'utilisateur sont manquantes.
Qu'indiquer à l'usager ?
Lorsqu'un usager rencontre ce type d'erreur, vous pouvez lui demander de réaliser une nouvelle tentative de connexion ou de choisir un autre mode de connexion.
S'il a la possibilité de nous contacter pour corriger le problème, il aura déjà été invité par FranceConnect ou FranceConnect+ à contacter le support afin que nous puissions l'accompagner dans la résolution de son problème.
Que faire pour corriger le problème ?
Il n'y a rien à faire à ce stade de votre côté.
Ce code d'erreur indique qu'une erreur inattendue s'est produite sur le serveur FranceConnect ou FranceConnect+ lors du traitement d'une requête et qu'il n'a pas été possible de réaliser l'action attendue.
Qu'indiquer à l'usager ?
Lorsqu'un usager rencontre ce type d'erreur, vous pouvez lui demander de réaliser une nouvelle tentative de connexion ou de choisir un autre mode de connexion.
Que faire pour corriger le problème ?
Il se peut que ce problème soit temporaire et qu'une nouvelle tentative de connexion suffise. Si le problème persiste, nous vous invitons à contacter le support partenaire FranceConnect pour que nous puissions analyser et corriger le problème.
Ce code d'erreur indique que FranceConnect ou FranceConnect+ est temporairement indisponible.
Qu'indiquer à l'usager ?
Lorsqu'un usager rencontre ce type d'erreur, vous pouvez lui demander de réaliser une nouvelle tentative de connexion ou de choisir un autre mode de connexion.
Que faire pour corriger le problème ?
Le problème est temporaire. Il suffit de refaire une nouvelle tentative de connexion quelques instants plus tard. Cela devrait fonctionner normalement.
Si le problème persiste, nous vous invitons à contacter le support partenaire FranceConnect pour que nous puissions analyser et corriger le problème.
En Bref
En cas d’erreur, l’utilisateur est redirigé vers la redirect_uri, accompagnée du paramètre error, conformément aux spécifications du protocole OpenID Connect.
Il est alors recommandé d’informer clairement l’utilisateur qu’un incident est survenu lors de son authentification, et de lui proposer une nouvelle tentative de connexion via FranceConnect ou, le cas échéant, une solution alternative.