🇫🇷 Français | 🇬🇧 English
Authorization Code Flow
Objective
The Authorization Code flow is the main integration method for L’Identité Numérique La Poste.
It allows partners to:
- authenticate a user
- retrieve identity data
- ensure a high level of security
Principle
The flow is based on a multi-step exchange:
- User redirection to LINLP
- Authentication (mobile)
- Return with a temporary code
- Exchange the code for tokens
- Retrieve user data
👉 This flow complies with the OpenID Connect standard.
Step 1: /authorize request
The partner redirects the user to LINLP.
GET /authorize
Main parameters:
- client_id
- redirect_uri
- response_type=code
- scope
- state (recommended)
- nonce (recommended)
- login_hint (optional)
Example:
https://authent.pprod.lidentitenumerique.laposte.fr/auth/realms/partenaire/protocol/openid-connect/auth ?client_id=XXX &response_type=code &redirect_uri=https://myservice.com/callback &scope=openid+profile+email &state=abc123 &nonce=xyz456
💡 `login_hint` can be used to prefill the user’s phone number.
Step 2: User authentication
The user:
- is redirected to LINLP
- receives a notification on their mobile device
- validates using their secret PIN code
👉 Data consent is requested when required.
Step 3: Redirection with code
After success:
https://myservice.com/callback?code=ABC123&state=abc123
⚠️ The code:
- is temporary (short lifetime)
- is single-use
Step 4: Code exchange (/token)
The backend calls:
POST /token
Example:
grant_type=authorization_code code=ABC123 redirect_uri=https://myservice.com/callback
👉 Authentication is required through:
- client_id
- client_secret
Step 5: Token retrieval
Response:
- access_token
- id_token (signed JWT)
- expires_in
Step 6: User data retrieval (/userinfo)
GET /userinfo Authorization: Bearer access_token
👉 Returns:
- user data (claims)
- contextual information
🔐 Critical Recommendation
⚠️ The partner must retain the id_token
👉 Why?
- it constitutes the proof of user authentication
- it is signed by LINLP
- it can be cryptographically verified at any time
- it does not depend on LINLP availability
👉 Use cases:
- login audit trail
- legal proof
- post-event verification
- dispute management
💡 Unlike the access_token, the id_token should be retained by the partner
Error Cases
/authorize errors
| Case | Behavior |
|---|---|
| Invalid scope | Redirection with error=invalid_scope |
| Invalid client_id | HTTP 400 error |
| Invalid redirect_uri | HTTP 400 error |
User-side errors
| Case | Behavior |
|---|---|
| User refusal | Return to login page |
| Validation timeout | Return to login page |
| Unknown user | Timeout |
/token errors
| Case | Description |
|---|---|
| Invalid code | invalid_grant |
| Expired code | invalid_grant |
| Invalid client_secret | unauthorized_client |
/userinfo errors
| Case | Description |
|---|---|
| Invalid token | invalid_token |
| Expired token | access denied |
Best Practices
⚠️ Always use a backend
- Never call `/token` from the frontend.
⚠️ Validate the state parameter
- Prevents CSRF attacks.
⚠️ Validate the nonce
- Prevents replay attacks.
⚠️ Verify the id_token signature
- Ensures data integrity.
⚠️ Handle expirations
- Codes and tokens expire quickly.
⚠️ Log errors
- Essential for support and debugging.
Points of Attention
⚠️ redirect_uri must match exactly
- Otherwise the request is rejected.
⚠️ Scopes must be declared in advance
- They cannot be added dynamically.
⚠️ The flow is synchronous for the user
- Plan an appropriate UX (loading, waiting screens).
⚠️ Returned data depends on:
- requested scopes
- LINLP configuration
- user consent
Summary
- Standard OpenID Connect flow
- Based on redirection + secure token exchange
- Returns tokens including the key id_token
- Recommended for all web and mobile use cases
Next Step
👉 For advanced use cases: