====== Scopes et claims ======

===== Objectif =====

Les données retournées par L’Identité Numérique La Poste sont définies via les **scopes OpenID Connect**.

👉 Un scope correspond à un ensemble de données (claims) que le partenaire demande lors de l’authentification.

-----

===== Principe =====

Lors de l’appel `/authorize`, le partenaire précise les données souhaitées :

<code>
scope=openid+profile+email+phone
</code>

👉 LINLP retourne la donnée uniquement si les 3 conditions sont respectées :
  * la donnée est demandée ou préconfigurée par défaut 
  * la donnée est autorisée dans le paramétrage LINLP
  * la donnée est consentie par l’utilisateur

-----

===== Notions clés =====

^ Terme ^ Description ^
| Scope | Groupe de données |
| Claim | Donnée individuelle |
| id_token | Contient des claims |
| /userinfo | Retourne des claims |

-----

===== ⚠️ Donnée non vérifiée : nom d’usage =====

⚠️ **Le champ `preferred_username` (nom d’usage) n’est pas une donnée vérifiée par LINLP.**

  * Cette donnée est **saisie librement par l’utilisateur**
  * Elle **n’est pas contrôlée** lors de la vérification d’identité
  * Elle est **souvent absente ou non à jour** sur les pièces d’identité

👉 En conséquence :
  * elle **ne doit pas être utilisée comme donnée d’identité de référence**
  * elle doit être considérée comme **indicative uniquement**

-----

===== Scopes disponibles =====

===== Scope openid =====

^ Claim ^ Description ^ Format ^ Exemple ^
| sub | Identifiant unique utilisateur | UUID | 075ccece-6699-4c08-80ca-27a6af136b68 |

-----

===== Scope profile =====

^ Claim ^ Description ^ Format ^ Exemple ^
| given_name | Prénoms | String | Jean Pierre |
| family_name | Nom de naissance | String | DUPONT |
| preferred_username | Nom d’usage **(non vérifié)** | String | MARTIN |
| gender | Sexe (Male / Female) | String | Male |

-----

===== Scope birth =====

^ Claim ^ Description ^ Format ^ Exemple ^
| birthdate | Date de naissance | YYYY-MM-DD | 1990-05-10 |
| birthplace | Code INSEE commune | String (5) | 75109 |
| birthdepartment | Département | String | 75 |
| birthcountry | Pays de naissance | String (5) | 99100 |

-----

===== Scope email =====

^ Claim ^ Description ^ Format ^ Exemple ^
| email | Adresse email | email | jean.dupont@mail.com |
| email_verified | Email vérifié | boolean | true |

-----

===== Scope phone =====

^ Claim ^ Description ^ Format ^ Exemple ^
| phone_number | Numéro de téléphone | +33XXXXXXXXX | +33601020304 |
| phone_number_verified | Téléphone vérifié | boolean | true |

-----

===== Scope nationality =====

^ Claim ^ Description ^ Format ^ Exemple ^
| nationality | Nationalité | JSON {code, label} | {"code":"FRA","label":"Française"} |

-----

===== Scope digital_identity_metadata =====

^ Claim ^ Description ^ Format ^ Exemple ^
| digital_identity_creation_date | Date de création identité | datetime | 2025-01-17T08:23:27.000Z |
| digital_identity_expiration_date | Date d’expiration | datetime | 2030-01-17T08:23:27.000Z |

-----

===== Scope identity_document_metadata =====

^ Claim ^ Description ^ Format ^ Exemple ^
| identity_document_mrz | Bande MRZ de la pièce d'identité | String | IDFRAXXXXXXX005<<<<<<<<<<<<<<<999999XXXXXXXXFRA<<<<<<<<<<<9XXXXXX<<XXXXX<<<<<<<<<<<<<<<<< |
| identity_document_type | Type de pièce | String | ID_CARD |
| identity_document_expiration_date | Date d'expiration de la pièce | Date | 2030-01-18 |
| identity_document_emitting_country | Pays d'emission | String | FRA |
| identity_document_emitting_date | Date d'emission | Date | 2020-01-18 |

-----

===== Données complémentaires =====

Certaines données peuvent être retournées en complément des scopes :

^ Claim ^ Description ^ Format ^ Exemple ^
| ccu_id | Identifiant interne La Poste | String (13) | 5572916534921 |
| splitted_given_name | Prénoms séparés | JSON | {"first_name":"Jean","middle_name":"Pierre"} |
| majority | Statut majeur | boolean | true |

-----

===== Données structurées =====

Certaines données sont retournées sous forme d’objets JSON :

===== Nationalité =====

<code>
"nationality": {
  "code": "FRA",
  "label": "Française"
}
</code>

-----

===== Téléphone structuré =====

<code>
"phone": {
  "country_prefix": "+33",
  "phone_number": "601020304"
}
</code>

-----

===== Prénoms détaillés =====

<code>
"splitted_given_name": {
  "first_name": "Jean",
  "middle_name": "Pierre Louis"
}
</code>

-----

===== Exemple de réponse (/userinfo) =====

<code>
{
  "sub": "5577832670193",
  "given_name": "Jean Pierre",
  "family_name": "Dupont",
  "preferred_username": "Martin",
  "birthdate": "1990-05-10",
  "email": "jean.dupont@mail.com",
  "phone_number": "+33601020304"
}
</code>

-----

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

⚠️ Demander uniquement les données nécessaires  
Respect du principe de minimisation.

⚠️ Ne pas utiliser le nom d’usage comme donnée fiable  
Utiliser `family_name` comme référence.

-----

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

⚠️ Les scopes doivent être validés en amont  
Impossible de demander un scope non autorisé.

⚠️ Les formats sont normalisés  
Respecter les formats (date, codes INSEE, etc.).

-----

===== Bon à savoir =====

💡 Toutes les données :
  * sont transmises uniquement après consentement utilisateur
  * peuvent évoluer selon le paramétrage du partenaire

-----

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

  * Les données sont pilotées par les scopes
  * Les claims sont les données individuelles
  * Les données sont retournées aux formats JWT et JSON
  * Le nom d’usage est une donnée déclarative non vérifiée

-----

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

👉 Comprendre les tokens :

[[donnees:jwt_et_userinfo|JWT et userinfo]]