A3BC — Build digital trust. Together.
Français English
Documentation menu
Documentation/Getting started/Understanding OIDC

Understanding OIDC

The essential notions, explained simply, for someone new to OpenID Connect.

If you have never used OpenID Connect (OIDC), read this page first: ten minutes are enough to understand what you are going to build.

The problem OIDC solves

Your service needs to know a person (name, age, address, an identity document…) without asking them to type everything again, and with verified information. The person already has this information in their TrustMe app. OIDC is the protocol that lets TrustMe pass it to you only if the person consents, without you ever seeing their TrustMe credentials.

The actors

Actor Role
The user Wants to sign up or sign in with you. Approves in the TrustMe app what they agree to share.
Your service (the Relying Party, RP) You. You ask for information and receive it.
The browser Carries the user between your site and A3BC.
A3BC OIDC (the Identity Provider) Orchestrates authentication and consent, then hands you the information.
The TrustMe app Where the user authenticates and consents (by entering an identifier, or scanning a QR code).

The journey, one sentence per step

  1. The user clicks “Sign in with TrustMe” on your site.
  2. Your server redirects them to A3BC, stating what you want (the scopes).
  3. The user approves in the TrustMe app: they consent.
  4. A3BC redirects them back to your site with a temporary code.
  5. Your server exchanges this code for tokens (proving its identity with its client_secret).
  6. You read the information in the token and, if needed, call other APIs (documents, delayed sharing).

The four notions to remember

Scope: what you ask for, by theme. For example email, private:person (civil status), private:doc.id (identity document). The more scopes you request, the more the user must agree to share: only request what is needed. See the scope list.

Claim: a specific piece of information (given_name, birthdate, email…). A scope gives access to one or more claims. See the claim list.

Consent: the person chooses what they share, in each transaction. They can refuse, and revoke later in the case of delayed sharing.

Tokens: strings you receive. There are several and they serve different purposes: the code (temporary, single-use), the id_token (the signed proof of identity and the claims) and the access_token (the key to call APIs that read what the user shared). The Tokens and lifetimes page details each.

Why so many precautions?

Mechanism What it is for, in plain words
client_secret Your service’s “password”. It proves it is really you exchanging the code. It stays on your server, never in a browser or mobile app.
redirect_uri The address where A3BC sends the user back. It must be declared in advance: this prevents a third party from diverting the code to their own site.
state A random ticket number you generate before the redirect and find again on return. If the return does not carry your ticket, it does not come from a sign-in you started: reject it.
nonce A second random number, written inside the id_token. It guarantees the token belongs to your transaction and is not replayed.
id_token signature Proves the token was really issued by A3BC and was not modified.

What you will have to build

  • A /login endpoint that generates state and nonce then redirects to A3BC.
  • A /callback endpoint (your redirect_uri) that checks state, exchanges the code, verifies the id_token and stores the information.
  • Optional: a webhook endpoint if you use delayed sharing.

A complete program of under 150 lines is provided in the end-to-end example.

Glossary

Term Definition
ACR Authentication level of assurance (e.g. a3bc2, two factors).
Callback The URL of your service where the user comes back after consent.
Discovery A public JSON document listing all A3BC endpoints.
IdP Identity Provider: A3BC / TrustMe.
JWKS A3BC’s public keys, used to verify the id_token signature.
JWT Format of the id_token: three encoded parts separated by dots, one of which is a signature.
RP Relying Party: your service.
Sandbox The test environment. No real data.
sub The user identifier specific to your service.
Webhook An HTTP call A3BC makes to your server to notify you of an event.