Documentation/Démarrer/Comprendre OIDC

Comprendre OIDC

Les notions essentielles, expliquées simplement, pour quelqu'un qui découvre OpenID Connect.

Si vous n’avez jamais utilisé OpenID Connect (OIDC), lisez cette page d’abord : une dizaine de minutes suffisent pour comprendre ce que vous allez coder.

Le problème que résout OIDC

Votre service a besoin de connaître une personne (son nom, son âge, son adresse, une pièce d’identité…) sans lui demander de tout ressaisir, et avec une information vérifiée. La personne a déjà ces informations dans son application TrustMe. OIDC est le protocole qui permet à TrustMe de vous les transmettre uniquement si la personne y consent, sans que vous ne voyiez jamais ses identifiants TrustMe.

Les acteurs

Acteur	Rôle
L’utilisateur	Souhaite s’inscrire ou se connecter chez vous. Valide dans l’app TrustMe ce qu’il accepte de partager.
Votre service (le Relying Party, RP)	Vous. Vous demandez des informations et les recevez.
Le navigateur	Transporte l’utilisateur entre votre site et A3BC.
A3BC OIDC (l’Identity Provider)	Orchestre l’authentification et le consentement, puis vous remet les informations.
L’app TrustMe	Là où l’utilisateur s’authentifie et consent (par saisie d’un identifiant, ou en scannant un QR code).

Le parcours, en une phrase par étape

L’utilisateur clique sur « Se connecter avec TrustMe » sur votre site.
Votre serveur le redirige vers A3BC en indiquant ce que vous voulez (les scopes).
L’utilisateur valide dans l’app TrustMe : il consent.
A3BC le redirige vers votre site avec un code temporaire.
Votre serveur échange ce code contre des jetons (en prouvant son identité avec son client_secret).
Vous lisez les informations dans le jeton, et au besoin appelez d’autres API (documents, partage différé).

Les quatre notions à retenir

Scope : ce que vous demandez, par thème. Par exemple email, private:person (état civil), private:doc.id (pièce d’identité). Plus vous demandez de scopes, plus l’utilisateur doit accepter de partager : ne demandez que le nécessaire. Voir la liste des scopes.

Claim : une information précise (given_name, birthdate, email…). Un scope donne accès à un ou plusieurs claims. Voir la liste des claims.

Consentement : la personne choisit ce qu’elle partage, à chaque transaction. Elle peut refuser, et révoquer plus tard dans le cas du partage différé.

Jetons : des chaînes de caractères que vous recevez. Il y en a plusieurs et ils servent à des choses différentes : le code (temporaire, à usage unique), l’id_token (la preuve signée de l’identité et les claims) et l’access_token (la clé pour appeler les API en lisant ce que l’utilisateur a partagé). La page Jetons et durées de vie détaille chacun.

Pourquoi tant de précautions ?

Mécanisme	À quoi il sert, en clair
`client_secret`	Le « mot de passe » de votre service. Il prouve que c’est bien vous qui échangez le code. Il reste sur votre serveur, jamais dans un navigateur ni une application mobile.
`redirect_uri`	L’adresse où A3BC renvoie l’utilisateur. Elle doit être déclarée à l’avance : cela empêche un tiers de détourner le code vers son propre site.
`state`	Un numéro de ticket aléatoire que vous générez avant la redirection et que vous retrouvez au retour. Si le retour ne porte pas votre ticket, il ne vient pas d’une connexion que vous avez lancée : rejetez-le.
`nonce`	Un second numéro aléatoire, écrit dans l’id_token. Il garantit que le jeton correspond à votre transaction et qu’il n’est pas rejoué.
Signature de l’`id_token`	Prouve que le jeton a bien été émis par A3BC et n’a pas été modifié.

Ce que vous allez devoir coder

Un endpoint /login qui génère state et nonce puis redirige vers A3BC.
Un endpoint /callback (votre redirect_uri) qui vérifie state, échange le code, vérifie l’id_token et enregistre les informations.
Optionnel : un endpoint webhook si vous utilisez le partage différé.

Un programme complet de moins de 150 lignes est fourni dans l’exemple de bout en bout.

Glossaire

Terme	Définition
ACR	Niveau de garantie de l’authentification (ex. `a3bc2`, deux facteurs).
Callback	L’URL de votre service où l’utilisateur revient après le consentement.
Discovery	Un document JSON public qui liste tous les endpoints d’A3BC.
IdP	Identity Provider : A3BC / TrustMe.
JWKS	Les clés publiques d’A3BC, qui servent à vérifier la signature de l’id_token.
JWT	Format du jeton `id_token` : trois parties encodées séparées par des points, dont une signature.
RP	Relying Party : votre service.
Sandbox	L’environnement de test. Aucune donnée réelle.
`sub`	L’identifiant de l’utilisateur propre à votre service.
Webhook	Un appel HTTP qu’A3BC fait vers votre serveur pour vous prévenir d’un événement.