API Rôles et Permissions

Auris implémente un modèle d’autorisation à trois niveaux. Cette API couvre deux de ces niveaux :

RBAC (Role-Based Access Control) : Les rôles sont des ensembles nommés de permissions. Les utilisateurs sont assignés à des rôles. Les permissions utilisent le format action:ressource (ex. view:invoices, manage:users). Chaque permission peut être définie à ALLOW, DENY ou INHERIT (modèle tri-état).
FGA (Fine-Grained Authorization) : Un moteur de tuples relationnels compatible Zanzibar pour le contrôle d’accès au niveau objet. Le niveau FGA est utilisé quand l’RBAC au niveau rôle est insuffisant — par exemple, “l’utilisateur Alice peut voir le document 42 spécifiquement, même si elle n’a pas view:all_documents.”

RBAC — Gestion des Rôles

Tous les endpoints de gestion des rôles nécessitent la permission manage:roles et le header x-tenant.

GET/api/rolesRequires: manage:roles

Liste tous les rôles définis dans le tenant. Retourne les métadonnées du rôle mais pas la liste complète des permissions. Utilise GET /api/roles/[id] ou GET /api/roles/[id]/permissions pour les détails des permissions.

Paramètres de query

Paramètre	Type	Description
`page`	integer	Numéro de page (défaut : 1)
`limit`	integer	Éléments par page (défaut : 20)
`search`	string	Filtre par nom de rôle

Réponse de succès


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "role_abc123",
        "name": "editor",
        "description": "Peut créer et modifier du contenu",
        "color": "#3b82f6",
        "userCount": 12,
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
  }
}

POST/api/rolesRequires: manage:roles

Crée un nouveau rôle. Les noms de rôle doivent être uniques dans le tenant et ne peuvent contenir que des caractères alphanumériques, des tirets et des underscores.

Corps de la requête


{
  "name": "billing-admin",
  "description": "Gère les factures et les méthodes de paiement",
  "color": "#f59e0b"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "id": "role_def456",
    "name": "billing-admin",
    "description": "Gère les factures et les méthodes de paiement",
    "color": "#f59e0b",
    "createdAt": "2025-02-18T10:00:00Z"
  }
}

Codes d’erreur

Code	HTTP	Description
`NAME_TAKEN`	409	Un rôle avec ce nom existe déjà
`VALIDATION_ERROR`	400	Format du nom de rôle invalide

GET/api/roles/[id]Requires: manage:roles

Obtient un rôle par ID, incluant la liste complète des permissions avec l’état ALLOW/DENY pour chaque permission.

Réponse de succès


{
  "ok": true,
  "data": {
    "id": "role_abc123",
    "name": "editor",
    "description": "Peut créer et modifier du contenu",
    "color": "#3b82f6",
    "permissions": [
      { "id": "perm_1", "key": "view:invoices", "state": "ALLOW" },
      { "id": "perm_2", "key": "create:invoices", "state": "ALLOW" },
      { "id": "perm_3", "key": "delete:invoices", "state": "DENY" }
    ]
  }
}

États des permissions : ALLOW (explicitement accordé), DENY (explicitement bloqué), INHERIT (non défini explicitement — utilise le défaut du système, typiquement deny).

PUT/api/roles/[id]Requires: manage:roles

Met à jour le nom, la description ou la couleur d’un rôle.

DELETE/api/roles/[id]Requires: manage:roles

Supprime un rôle. Les utilisateurs qui ont ce rôle assigné le perdront immédiatement. Le rôle est retiré de tous les utilisateurs puis supprimé du tenant.

La suppression d’un rôle affecte tous les utilisateurs qui le possèdent. Vérifie l’impact en utilisant GET /api/roles/[id] qui inclut userCount avant de supprimer.

RBAC — Gestion des Permissions

GET/api/roles/[id]/permissionsRequires: manage:roles

Liste les paramètres des permissions pour un rôle, regroupées par catégorie. Chaque permission a un état ALLOW, DENY ou INHERIT.

Réponse de succès


{
  "ok": true,
  "data": {
    "permissions": [
      {
        "category": "Documents",
        "items": [
          { "id": "perm_1", "key": "view:invoices", "label": "Voir les Factures", "state": "ALLOW" },
          { "id": "perm_2", "key": "create:invoices", "label": "Créer des Factures", "state": "ALLOW" },
          { "id": "perm_3", "key": "delete:invoices", "label": "Supprimer des Factures", "state": "INHERIT" }
        ]
      }
    ]
  }
}

PUT/api/roles/[id]/permissionsRequires: manage:roles

Met à jour les états des permissions pour un rôle. Envoie un tableau d’objets avec l’état de la permission. Les permissions non incluses dans le tableau sont laissées inchangées.

Corps de la requête


{
  "permissions": [
    { "permissionId": "perm_1", "state": "ALLOW" },
    { "permissionId": "perm_3", "state": "DENY" }
  ]
}

Réponse de succès


{
  "ok": true,
  "data": {
    "updated": 2,
    "permissions": [
      { "id": "perm_1", "key": "view:invoices", "state": "ALLOW" },
      { "id": "perm_3", "key": "delete:invoices", "state": "DENY" }
    ]
  }
}

Vérification des Permissions

POST/api/roles/checkRequires: authenticated user

Vérifie si l’utilisateur authentifié courant a un ensemble de permissions. Résout les permissions à travers tout le stack RBAC : overrides directs sur l’utilisateur, assignations de rôles et politiques par défaut. Optionnellement scopé à une application spécifique.

Corps de la requête


{
  "permissions": ["view:invoices", "create:invoices", "approve:expenses"],
  "applicationId": "app_abc123"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "permissions": {
      "view:invoices": true,
      "create:invoices": true,
      "approve:expenses": false
    }
  }
}

FGA — Modèles d’Autorisation

Le moteur d’Autorisation Fine-Grained utilise un modèle basé sur un DSL pour définir les types d’objets, les relations et les règles de réécriture. Avant d’écrire des tuples, tu dois créer et activer un modèle d’autorisation.

Tous les endpoints FGA nécessitent le header x-tenant.

GET/api/fga/modelsRequires: manage:fga_models

Liste tous les modèles d’autorisation pour le tenant. Un seul modèle peut être actif à la fois.

Réponse de succès


{
  "ok": true,
  "data": [
    {
      "id": "model_abc123",
      "name": "Modèle d'Autorisation SaaS",
      "version": 3,
      "isActive": true,
      "createdAt": "2025-02-10T00:00:00Z"
    }
  ]
}

POST/api/fga/modelsRequires: manage:fga_models

Crée un nouveau modèle d’autorisation en fournissant une définition DSL. Le DSL est analysé et validé avant le stockage. Si la validation échoue, un message d’erreur détaillé est retourné.

Corps de la requête


{
  "name": "Modèle Accès Documents",
  "dsl": "type user\n\ntype document\n  relations\n    define owner: [user]\n    define viewer: [user] or owner\n"
}

Codes d’erreur

Code	HTTP	Description
`DSL_PARSE_ERROR`	400	Syntaxe DSL invalide — l’erreur inclut le numéro de ligne et la description
`DSL_VALIDATION_ERROR`	400	Le DSL est syntaxiquement valide mais fait référence à des types ou relations non définis

POST/api/fga/models/[id]/activateRequires: manage:fga_models

Définit ce modèle comme modèle d’autorisation actif pour le tenant. Désactive tout modèle précédemment actif. Tous les appels check, expand et list-objects suivants utilisent ce modèle.

Réponse de succès


{
  "ok": true,
  "data": { "activated": true, "modelId": "model_def456" }
}

FGA — Tuples Relationnels

Les tuples sont les faits du système d’autorisation. Chaque tuple affirme qu’un sujet a une relation avec un objet.

Format tuple : typeObjet:idObjet#relation@typeSujet:idSujet

Exemple : document:readme#viewer@user:alice — l’utilisateur alice est un viewer du document readme.

GET/api/fga/tuplesRequires: view:fga_tuples

Liste les tuples relationnels, avec filtrage optionnel.

Paramètres de query

Paramètre	Type	Description
`objectType`	string	Filtre par type d’objet (ex. `document`)
`objectId`	string	Filtre par ID objet
`relation`	string	Filtre par nom de relation
`subjectType`	string	Filtre par type sujet
`subjectId`	string	Filtre par ID sujet

POST/api/fga/tuplesRequires: manage:fga_tuples

Écrit un seul tuple relationnel. Le tuple est validé par rapport au modèle d’autorisation actif avant le stockage.

Corps de la requête


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Pour les références subject-set (ex. “tous les membres du groupe engineering peuvent voir”) :


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "group",
  "subjectId": "engineering",
  "subjectRelation": "member"
}

Codes d’erreur

Code	HTTP	Description
`NO_ACTIVE_MODEL`	400	Aucun modèle d’autorisation actif pour valider
`INVALID_RELATION`	400	La relation n’existe pas sur ce type d’objet dans le modèle actif
`TUPLE_EXISTS`	409	Un tuple identique existe déjà (préfère l’écriture bulk — idempotente)

POST/api/fga/tuples/bulkRequires: manage:fga_tuples

Écrit ou supprime plusieurs tuples en une seule requête. Les opérations sont traitées atomiquement — si une opération échoue à la validation, toute la requête bulk est rejetée.

Corps de la requête


{
  "writes": [
    {
      "objectType": "document",
      "objectId": "readme",
      "relation": "editor",
      "subjectType": "user",
      "subjectId": "bob"
    }
  ],
  "deletes": [
    {
      "objectType": "document",
      "objectId": "readme",
      "relation": "viewer",
      "subjectType": "user",
      "subjectId": "alice"
    }
  ]
}

FGA — Requêtes d’Autorisation

POST/api/fga/checkRequires: debug:fga

Vérifie si un sujet a une relation spécifique avec un objet. Évalue les règles de réécriture complètes de manière récursive. Retourne optionnellement l’arbre de résolution pour le débogage.

Corps de la requête


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice",
  "explain": true
}

Réponse de succès


{
  "ok": true,
  "data": {
    "allowed": true,
    "resolution": {
      "type": "union",
      "result": true,
      "children": [
        {
          "type": "this",
          "relation": "viewer",
          "result": true,
          "tupleFound": "document:readme#viewer@user:alice"
        }
      ]
    }
  }
}

POST/api/fga/expandRequires: debug:fga

Développe une relation pour lister tous les sujets (utilisateurs ou ensembles d’utilisateurs) qui ont une certaine relation avec un objet.

Corps de la requête


{
  "objectType": "document",
  "objectId": "readme",
  "relation": "viewer"
}

POST/api/fga/list-objectsRequires: debug:fga

Liste tous les objets d’un type donné auxquels un sujet peut accéder via une relation spécifique.

Corps de la requête


{
  "objectType": "document",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Réponse de succès


{
  "ok": true,
  "data": {
    "objectIds": ["readme", "api-spec", "changelog"],
    "total": 3
  }
}

Les endpoints check, expand et list-objects nécessitent debug:fga car ils exposent la structure interne du modèle d’autorisation. En production, les resource servers devraient appeler ces endpoints en utilisant un token M2M avec cette permission plutôt que de les exposer aux utilisateurs finaux.

Pages Associées

Guide Rôles et Permissions — Comment fonctionne l’RBAC dans Auris
Autorisation Fine-Grained — Autorisation avancée avec FGA
Utilisateurs et Rôles — Assigne des rôles depuis la Console
FGA Débogueur — Teste les vérifications d’autorisation dans la Console