Rôles et RBAC

Rôles système, rôles personnalisés bâtis sur un catalogue fixe de permissions, et un invariant anti-escalade qui rend l'escalade de privilèges structurellement impossible.

Les rôles gouvernent qui peut faire quoi dans la console d'administration et l'API admin de votre organisation. Le modèle est deny-by-default : une permission absente d'un rôle est refusée, côté serveur, sur chaque endpoint.

Rôles système

Chaque membre d'une organisation détient exactement un rôle. Trois rôles système sont intégrés :

Rôle	Signification
`owner`	Contrôle total, y compris attribuer ou retirer le rôle `owner`
`admin`	Administration du quotidien, toutes les permissions du catalogue
`member`	Utilisateur ordinaire, aucune permission d'administration

owner et admin détiennent actuellement le même ensemble de permissions ; la différence est que seul un owner peut attribuer ou retirer le rôle owner. Un member ne voit aucune console d'administration au-delà de son propre profil.

Le catalogue de permissions

Les rôles personnalisés se construisent sur un catalogue fixe, défini côté serveur. Toute permission hors catalogue est rejetée.

Clé	Donne le droit de
`users:view`	Voir l'annuaire des utilisateurs
`apps:manage`	Créer, modifier et supprimer les applications OAuth
`audit:view`	Consulter le journal d'audit
`members:manage`	Attribuer et retirer les rôles des membres
`tenant:manage`	Paramètres du tenant, politiques, SSO, domaines, marque
`roles:manage`	Définir des rôles personnalisés
`groups:manage`	Gérer les groupes d'utilisateurs

Rôles personnalisés

Un rôle personnalisé a une clé (un slug minuscule de 2 à 40 caractères respectant ^[a-z][a-z0-9-]{1,39}$ ; owner, admin et member sont réservés), un nom d'affichage et n'importe quel sous-ensemble du catalogue.

La résolution est pilotée par les données : quand une requête est autorisée, la chaîne de rôle du membre se résout soit vers la table statique des rôles système, soit vers le rôle personnalisé stocké pour le tenant. Un rôle inconnu ou supprimé se résout en ensemble de permissions vide, donc fail-closed : son porteur redevient un membre ordinaire.

L'invariant anti-escalade

Une seule règle d'inclusion ensembliste protège tout le modèle : on ne peut définir, modifier, supprimer ou attribuer qu'un rôle dont les permissions sont toutes incluses dans les siennes.

Créer ou mettre à jour un rôle dont les permissions dépassent les vôtres est refusé.
La modification est symétrique : on ne peut pas réécrire (ni supprimer) un rôle dont les permissions actuelles dépassent les siennes, si bien qu'un porteur de roles:manage à périmètre réduit ne peut pas saboter un rôle plus puissant.
L'attribution suit la même règle d'inclusion, et le rôle système owner ne peut être accordé que par un owner.

Conséquence : aucune séquence d'opérations ne peut jamais conférer à quiconque une permission que l'administrateur agissant ne détient pas déjà.

La console suit les permissions effectives

GET /v1/admin/context renvoie le rôle de l'appelant, ses permissions effectives et son tenant. La console s'en sert pour décider quelles sections afficher ; l'application des droits reste toujours côté serveur.

curl -sS https://accounts.obexal.com/v1/admin/context \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN"
# {"role": "support", "permissions": ["users:view", "audit:view"], "tenant": {...}}

Gérer les rôles par l'API

Les quatre endpoints exigent la permission roles:manage, avec un jeton d'API admin (Authorization: Bearer obx_...). Un domaine personnalisé remplace accounts.obexal.com.

Méthode et chemin	Effet
`GET /v1/admin/roles`	Lister les rôles personnalisés et le catalogue de permissions
`POST /v1/admin/roles`	Créer un rôle
`PUT /v1/admin/roles/{key}`	Mettre à jour le nom et les permissions
`DELETE /v1/admin/roles/{key}`	Supprimer le rôle et le retirer de ses porteurs

curl -sS -X POST https://accounts.obexal.com/v1/admin/roles \
  -H "Authorization: Bearer $OBEXAL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "support", "name": "Support niveau 1", "permissions": ["users:view", "audit:view"]}'
# 201 {"role": {"key": "support", "name": "Support niveau 1", "permissions": ["users:view", "audit:view"]}}

Supprimer un rôle le retire aussi de chaque membre qui le portait : ils redeviennent des membres ordinaires, si bien qu'aucune clé orpheline ne subsiste (recréer la même clé plus tard ne peut pas re-conférer silencieusement du pouvoir aux anciens porteurs). Le nombre de membres rétrogradés est consigné au journal d'audit, comme chaque création, mise à jour et suppression de rôle. Les rôles personnalisés font aussi partie du bundle déclaratif, voir Policy as code.

Les rôles ne voyagent pas dans les jetons

Les rôles gouvernent la console et l'API admin, rien d'autre. Ils ne voyagent jamais dans les jetons émis vers vos applications : les ID tokens et access tokens portent le claim groups (les noms des groupes de l'utilisateur), pas les rôles. Pour piloter l'autorisation dans vos propres applications, utilisez les groupes et l'accès aux applications.