Référence des scopes et claims

Vue d'ensemble des scopes

Trousseau implémente un modèle de scopes à trois niveaux. Chaque niveau s'appuie sur le précédent.

Niveau	Scope(s)	Description
1	`openid email profile`	Identité OIDC standard. Disponible pour tous les partenaires.
2	`trousseau:context`	Identifiants de l'écosystème. Opt-in par partenaire.
3	`trousseau:organization`	Appartenances organisationnelles. Opt-in pour les partenaires B2B.

Niveau 1 — OIDC standard

Ces scopes suivent la spécification OpenID Connect Core. Ils fonctionnent avec n'importe quelle bibliothèque cliente OIDC sans personnalisation.

`openid` (obligatoire)

Toujours requis. Indique à Trousseau de retourner un ID token.

Claim	Type	Description
`sub`	`string` (UUID)	Identifiant unique de l'utilisateur dans Trousseau. Stable entre les sessions.
`iss`	`string` (URL)	URL de l'émetteur — l'émetteur OIDC de votre application.
`aud`	`string`	Votre client ID.
`exp`	`number`	Expiration du token (timestamp Unix).
`iat`	`number`	Heure d'émission du token (timestamp Unix).

`email`

Claim	Type	Description
`email`	`string`	Adresse e-mail principale de l'utilisateur.
`email_verified`	`boolean`	Toujours `true`. Trousseau vérifie toutes les adresses e-mail.

`profile`

Claim	Type	Description
`name`	`string`	Nom d'affichage complet (ex. : `"Jean Dupont"`).
`given_name`	`string`	Prénom (ex. : `"Jean"`).
`family_name`	`string`	Nom de famille (ex. : `"Dupont"`).
`picture`	`string` (URL)	URL de l'avatar. Chaîne vide si non défini.

Exemple d'ID token (Niveau 1)

{
  "iss": "https://auth.keysuite.app/application/o/your-slug/",
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "aud": "your-slug-oidc",
  "exp": 1712400000,
  "iat": 1712399700,
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg"
}

Demandez le scope trousseau:context pour recevoir des identifiants à l'échelle de l'écosystème. Cela est utile lorsque votre application a besoin de corréler des utilisateurs entre plusieurs applications connectées à Trousseau.

Claim	Type	Description
`trousseau_user_id`	`string` (UUIDv7)	Identifiant utilisateur stable à l'échelle de l'écosystème. Partagé entre toutes les applications connectées à Trousseau. Contrairement à `sub` (qui est l'UUID interne d'Authentik), cet identifiant est portable et survit aux migrations d'IdP.
`locale`	`string` (BCP-47)	Langue préférée de l'utilisateur (ex. : `"fr-FR"`, `"en-GB"`).

Quand utiliser le Niveau 2

Vous avez besoin de faire correspondre des utilisateurs entre plusieurs applications connectées à Trousseau
Vous souhaitez prédéfinir la langue de l'interface en fonction des préférences de l'utilisateur
Vous avez besoin d'un identifiant utilisateur stable qui ne changera pas si le backend IdP est migré

Exemple d'ID token (Niveau 1 + 2)

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg",
  "trousseau_user_id": "018cc251-f400-78cc-8e0c-000fe440ee40",
  "locale": "fr-FR"
}

Niveau 3 — Organisation

Demandez le scope trousseau:organization pour recevoir les appartenances organisationnelles de l'utilisateur dans l'écosystème KeySuite. Ce niveau est conçu pour les partenaires B2B (PMS, outils de gestion hôtelière) ayant besoin de connaître la ou les organisation(s) dans lesquelles travaille l'utilisateur.

Claim	Type	Description
`organizations`	`array` d'objets	Toutes les organisations dont l'utilisateur est membre.

Objet organisation

Champ	Type	Description
`id`	`string` (UUIDv7)	Identifiant de l'organisation dans KeySuite.
`name`	`string`	Nom d'affichage de l'organisation.
`slug`	`string`	Identifiant compatible URL.
`role`	`string`	Rôle de l'utilisateur dans cette organisation : `admin`, `hr`, `accounting` ou `member`.

Quand utiliser le Niveau 3

Votre application est au service d'une organisation spécifique (hôtel, entreprise)
Vous avez besoin de limiter les actions des utilisateurs à un contexte organisationnel
Vous souhaitez afficher du contenu ou des permissions spécifiques à l'organisation

Gestion de plusieurs organisations

Un utilisateur peut appartenir à plusieurs organisations. Si votre application est spécifique à une organisation :

Vérifiez si l'utilisateur appartient à votre organisation cible en comparant organizations[].id ou organizations[].slug
Si l'utilisateur appartient à plusieurs organisations, présentez un sélecteur d'organisation
Stockez l'organisation sélectionnée dans la session de votre application

Exemple d'ID token (Niveau 1 + 2 + 3)

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "jean.dupont@hotel.com",
  "email_verified": true,
  "name": "Jean Dupont",
  "given_name": "Jean",
  "family_name": "Dupont",
  "picture": "https://auth.keysuite.app/media/avatars/jean-dupont.jpg",
  "trousseau_user_id": "018cc251-f400-78cc-8e0c-000fe440ee40",
  "locale": "fr-FR",
  "organizations": [
    {
      "id": "018cc251-f400-78cc-8e0c-000fe440ee40",
      "name": "Hotel Le Grand Paris",
      "slug": "hotel-le-grand-paris",
      "role": "admin"
    },
    {
      "id": "018dd362-a511-89dd-9f1d-111ff551ff51",
      "name": "Hotel Riviera Nice",
      "slug": "hotel-riviera-nice",
      "role": "member"
    }
  ]
}

Disponibilité des claims

Récapitulatif de la disponibilité de chaque claim :

Claim	ID Token	UserInfo	Access Token
`sub`	Oui	Oui	Non
`email`	Oui	Oui	Non
`email_verified`	Oui	Oui	Non
`name`	Oui	Oui	Non
`given_name`	Oui	Oui	Non
`family_name`	Oui	Oui	Non
`picture`	Oui	Oui	Non
`trousseau_user_id`	Oui	Oui	Non
`locale`	Oui	Oui	Non
`organizations`	Oui	Oui	Non

Tous les claims sont présents à la fois dans l'ID Token (JWT) et dans la réponse de l'endpoint UserInfo. L'access token est opaque et ne contient pas de claims utilisateur.

Demande de scopes

Les scopes sont demandés dans le paramètre scope de la requête d'autorisation, séparés par des espaces :

# Niveau 1 uniquement
scope=openid email profile

# Niveau 1 + 2
scope=openid email profile trousseau:context

# Niveau 1 + 2 + 3
scope=openid email profile trousseau:context trousseau:organization

Vous ne pouvez demander que les scopes qui ont été approuvés pour votre application lors de l'intégration. Demander des scopes non autorisés entraînera une erreur invalid_scope.