====== Flow Authorization Code ======

===== Objectif =====

Le flow **Authorization Code** est le mode d’intégration principal de L’Identité Numérique La Poste.

Il permet :
  * d’authentifier un utilisateur
  * de récupérer ses données d’identité
  * de garantir un haut niveau de sécurité

-----

===== Principe =====

Le flow repose sur un échange en plusieurs étapes :

  - Redirection utilisateur vers LINLP
  - Authentification (mobile)
  - Retour avec un code temporaire
  - Échange du code contre des tokens
  - Récupération des données utilisateur

👉 Ce flow est conforme au standard OpenID Connect.

-----

===== Étape 1 : appel /authorize =====

Le partenaire redirige l’utilisateur vers LINLP.

<code>
GET /authorize
</code>

Paramètres principaux :

  * client_id
  * redirect_uri
  * response_type=code
  * scope
  * state (recommandé)
  * nonce (recommandé)
  * login_hint (optionnel)

Exemple :

<code>
https://authent.pprod.lidentitenumerique.laposte.fr/auth/realms/partenaire/protocol/openid-connect/auth
?client_id=XXX
&response_type=code
&redirect_uri=https://monservice.fr/callback
&scope=openid+profile+email
&state=abc123
&nonce=xyz456
</code>

💡 `login_hint` permet de pré-remplir le téléphone utilisateur.

-----

===== Étape 2 : authentification utilisateur =====

L’utilisateur :

  * est redirigé vers LINLP
  * reçoit une notification sur son mobile
  * valide via son code secret

👉 Le consentement des données est demandé si nécessaire.

-----

===== Étape 3 : redirection avec code =====

Après succès :

<code>
https://monservice.fr/callback?code=ABC123&state=abc123
</code>

⚠️ Le code :
  * est temporaire (durée courte)
  * est à usage unique

-----

===== Étape 4 : échange du code (/token) =====

Le backend appelle :

<code>
POST /token
</code>

Exemple :

<code>
grant_type=authorization_code
code=ABC123
redirect_uri=https://monservice.fr/callback
</code>

👉 Authentification requise via :
  * client_id
  * client_secret

-----

===== Étape 5 : récupération des tokens =====

Réponse :

  * access_token
  * id_token (JWT signé)
  * expires_in

-----

===== Étape 6 : récupération des données (/userinfo) =====

<code>
GET /userinfo
Authorization: Bearer access_token
</code>

👉 Retour :
  * données utilisateur (claims)
  * informations de contexte

-----

===== 🔐 Recommandation critique =====

⚠️ Le partenaire doit impérativement **stocker le id_token**

👉 Pourquoi ?

  * il constitue la **preuve d’authentification de l’utilisateur**
  * il est **signé par LINLP**
  * il peut être **vérifié cryptographiquement à tout moment**
  * il ne dépend pas de la disponibilité de LINLP

👉 Cas d’usage :

  * audit de connexion
  * preuve légale
  * contrôle a posteriori
  * gestion de litiges

💡 Contrairement à l’access_token, le **id_token doit être conservé côté partenaire**

-----

===== Cas d’erreur =====

===== Erreurs côté /authorize =====

^ Cas ^ Comportement ^
| Scope invalide | Redirection avec error=invalid_scope |
| client_id incorrect | Erreur 400 |
| redirect_uri incorrect | Erreur 400 |

-----

===== Erreurs côté utilisateur =====

^ Cas ^ Comportement ^
| Refus utilisateur | Retour page login |
| Timeout validation | Retour page login |
| Utilisateur inconnu | Timeout |

-----

===== Erreurs côté /token =====

^ Cas ^ Description ^
| Code invalide | invalid_grant |
| Code expiré | invalid_grant |
| Mauvais client_secret | unauthorized_client |

-----

===== Erreurs côté /userinfo =====

^ Cas ^ Description ^
| Token invalide | invalid_token |
| Token expiré | accès refusé |

-----

===== Bonnes pratiques =====

⚠️ Toujours utiliser un backend
  * Ne jamais appeler `/token` depuis le frontend.

⚠️ Vérifier le paramètre state
  * Permet d’éviter les attaques CSRF.

⚠️ Vérifier le nonce
  * Permet d’éviter les attaques de rejeu.

⚠️ Vérifier la signature du id_token
  * Garantit l’intégrité des données.

⚠️ Gérer les expirations
  * Les codes et tokens expirent rapidement.

⚠️ Journaliser les erreurs
  * Indispensable pour le support et debug.

-----

===== Points d’attention =====

⚠️ redirect_uri doit être strictement identique
  * Sinon rejet automatique.

⚠️ Les scopes doivent être déclarés en amont
  * Impossible d’en ajouter dynamiquement.

⚠️ Le flow est synchrone côté utilisateur
  * Prévoir une UX adaptée (chargement, attente).

⚠️ Les données retournées dépendent :
  * des scopes demandés
  * du paramétrage LINLP
  * du consentement utilisateur

-----

===== Résumé =====

  * Flow standard OpenID Connect
  * Basé sur redirection + échange sécurisé
  * Retour de tokens dont le **id_token clé**
  * Recommandé pour tous les cas d’usage web et mobile

-----

===== Étape suivante =====

👉 Pour des cas avancés :

[[integration:flow_ciba|Flow CIBA]]