Autorisation Fine-Grained (FGA)

Auris FGA est un moteur d’autorisation basé sur les relations (ReBAC) de style Zanzibar pour le contrôle d’accès au niveau objet. Tandis que RBAC répond à “cet utilisateur a-t-il la permission view:invoices globalement ?”, FGA répond à “cet utilisateur a-t-il la relation viewer sur le document #123 spécifiquement ?”.

FGA est l’outil approprié quand l’autorisation dépend des relations entre des objets spécifiques — pas seulement des rôles utilisateur.

Cas d’usage courants :

• Un système de partage de documents où chaque document a des propriétaires, éditeurs et visualiseurs individuels
• Un SaaS multi-tenant où l’accès à un projet dépend de l’appartenance à l’organisation
• Un système de fichiers où les permissions d’un dossier sont héritées par son contenu
• Un portail B2B où les contacts clients ne peuvent voir que les données de leur propre organisation

Concepts Fondamentaux

Objets

Un objet est une entité dans ton système identifiée par un type et un ID, écrit comme type:id. Exemples :

• document:inv-2024-001
• folder:factures-q4
• project:redesign-site
• organization:acme-corp

Relations

Une relation décrit comment un sujet est connecté à un objet. Les relations sont définies dans le modèle d’autorisation. Exemples : owner, editor, viewer, member, admin.

Sujets

Un sujet est l’entité qui est autorisée. Les sujets sont également écrits comme type:id. Le type de sujet le plus courant est user. Les sujets peuvent aussi être des ensembles — organization:acme-corp#member signifie “quiconque est membre de l’organisation acme-corp”.

Tuples

Un tuple de relation est un fait stocké : (typeObjet, idObjet, relation, typeSujet, idSujet). Par exemple : “l’utilisateur alice est un viewer du document report-2024” est stocké comme :

{
  "objectType": "document",
  "objectId": "report-2024",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Modèles d’Autorisation

Le modèle d’autorisation est un schéma écrit dans un DSL compatible OpenFGA. Il définit quels types existent et quelles relations chaque type supporte.

Syntaxe DSL

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type project
  relations
    define org: [organization]
    define admin: [user] or admin from org
    define editor: [user] or admin
    define viewer: [user] or editor

type document
  relations
    define project: [project]
    define owner: [user]
    define editor: [user] or owner or editor from project
    define viewer: [user] or editor or viewer from project or member from org of project

Ce modèle définit :

• N’importe quel utilisateur peut être member ou admin d’une organisation
• Un projet appartient à une organisation ; les admins du projet héritent des admins de l’organisation
• Un document appartient à un projet ; l’ensemble de ses viewers inclut les viewers directs, les éditeurs, les viewers du projet et les membres de l’organisation

Types de Réécriture

Auris FGA supporte 6 types de réécriture pour calculer l’appartenance aux relations :

Créer et Activer un Modèle

Écrire des Tuples

Les tuples sont les données runtime — les relations effectives entre objets et sujets dans ton application.

// Partage un document avec un utilisateur (écrit un tuple)
await fetch('/api/fga/tuples', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    writes: [
      {
        objectType: 'document',
        objectId: 'report-2024',
        relation: 'viewer',
        subjectType: 'user',
        subjectId: 'bob',
      },
    ],
  }),
})
 
// Révoque l'accès (supprime un tuple)
await fetch('/api/fga/tuples', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    deletes: [
      {
        objectType: 'document',
        objectId: 'report-2024',
        relation: 'viewer',
        subjectType: 'user',
        subjectId: 'bob',
      },
    ],
  }),
})

Vérifier l’Autorisation

Check

L’endpoint check répond à “le sujet X a-t-il la relation R sur l’objet Y ?”

Expand

L’endpoint expand retourne l’ensemble complet des sujets qui ont une relation donnée sur un objet — utile pour le débogage et pour construire des panneaux de partage visibles aux utilisateurs.

List Objects

L’endpoint list-objects retourne tous les objets d’un type donné sur lesquels un sujet a une relation spécifiée — utile pour filtrer les résultats de requêtes.

Utilisation avec le SDK

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.votredomaine.com', clientId: 'votre-client-id' })
 
// Vérifie une seule relation
const { allowed } = await auris.fga.check({
  object: 'document:report-2024',
  relation: 'viewer',
  subject: 'user:bob',
})
console.log(allowed) // true | false
 
// Liste tous les documents que l'utilisateur courant peut visualiser
const { objects } = await auris.fga.listObjects({
  objectType: 'document',
  relation: 'viewer',
  subject: 'user:current',
})
console.log(objects) // ['document:report-2024', 'document:facture-001', ...]
 
// Écrit des tuples programmatiquement
await auris.fga.writeTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'editor',
    subjectType: 'user',
    subjectId: 'alice',
  },
])
 
// Supprime des tuples
await auris.fga.deleteTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'viewer',
    subjectType: 'user',
    subjectId: 'bob',
  },
])

import { useFga } from '@auris/react'
 
function DocumentPage({ documentId }) {
  const { check, listObjects, isLoading } = useFga()
  const [canEdit, setCanEdit] = useState(false)
 
  useEffect(() => {
    check({
      object: `document:${documentId}`,
      relation: 'editor',
    }).then((result) => setCanEdit(result.allowed))
  }, [documentId])
 
  return (
    <div>
      <h1>Document</h1>
      {canEdit ? (
        <button>Modifier le Document</button>
      ) : (
        <span>Lecture seule</span>
      )}
    </div>
  )
}
 
// Panneau de partage — montre qui a accès
function SharingPanel({ documentId }) {
  const { expand } = useFga()
  const [viewers, setViewers] = useState([])
 
  useEffect(() => {
    expand({
      objectType: 'document',
      objectId: documentId,
      relation: 'viewer',
    }).then((result) => setViewers(result.subjects))
  }, [documentId])
 
  return (
    <ul>
      {viewers.map((viewer) => (
        <li key={viewer.subjectId}>{viewer.subjectId}</li>
      ))}
    </ul>
  )
}

// Vérification FGA côté serveur dans un Route Handler ou Server Component
import { createServerFgaClient } from '@auris/nextjs/server'
import { getSession } from '@auris/nextjs/server'
 
export async function GET(req: Request, { params }: { params: { id: string } }) {
  const session = await getSession()
  if (!session) return Response.json({ error: 'Non autorisé' }, { status: 401 })
 
  const fga = await createServerFgaClient()
 
  const { allowed } = await fga.check({
    object: `document:${params.id}`,
    relation: 'viewer',
    subject: `user:${session.user.id}`,
  })
 
  if (!allowed) {
    return Response.json({ error: 'Accès refusé' }, { status: 403 })
  }
 
  const document = await getDocument(params.id)
  return Response.json(document)
}
 
// Filtre une liste aux seuls objets que l'utilisateur peut voir
export default async function DocumentsPage() {
  const session = await getSession()
  const fga = await createServerFgaClient()
 
  const { objects } = await fga.listObjects({
    objectType: 'document',
    relation: 'viewer',
    subject: `user:${session.user.id}`,
  })
 
  const documentIds = objects.map((o) => o.split(':')[1])
  const documents = await getDocumentsByIds(documentIds)
 
  return <DocumentList documents={documents} />
}

Patterns Courants

Modèle Google Drive

Une hiérarchie où les permissions des dossiers se propagent aux documents :

type user

type folder
  relations
    define owner: [user]
    define editor: [user] or owner
    define viewer: [user] or editor
    define parent: [folder]
    define editor_via_parent: editor from parent
    define viewer_via_parent: viewer from parent

type document
  relations
    define owner: [user]
    define parent_folder: [folder]
    define editor: [user] or owner or editor_via_parent from parent_folder
    define viewer: [user] or editor or viewer_via_parent from parent_folder

Modèle SaaS Multi-Tenant

L’appartenance à l’organisation contrôle l’accès aux projets et ressources :

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type project
  relations
    define organization: [organization]
    define admin: [user] or admin from organization
    define member: [user] or member from organization or admin

type resource
  relations
    define project: [project]
    define owner: [user]
    define editor: [user] or owner or admin from project
    define viewer: [user] or editor or member from project

Débogage avec la Console FGA

La Console Auris inclut un FGA Debugger dans Console → Autorisation → Débogueur avec trois outils :

• Check : Teste n’importe quelle combinaison objet/relation/sujet et voit l’arbre de résolution
• Expand : Visualise l’ensemble complet des sujets pour n’importe quelle relation
• List Objects : Trouve tous les objets auxquels un utilisateur a accès

L’arbre de résolution montre exactement quels tuples et réécritures du modèle ont conduit au résultat allowed: true ou allowed: false — indispensable pour diagnostiquer des résultats d’autorisation inattendus.

Templates de Modèle

La Console fournit trois templates de modèle pour démarrer rapidement :

• Basic : Modèle simple utilisateur/ressource avec owner, editor, viewer
• SaaS : Hiérarchie organisation → projet → ressource avec appartenance aux équipes
• Drive : Hiérarchie dossier/document imbriquée avec permissions héritées

Guides Associés

• Rôles et Permissions (RBAC) — Autorisation basée sur les rôles pour permissions au niveau application
• Claims JWT Personnalisés — Intègre des données issues de FGA dans les access tokens
• Credentials M2M Client — Vérifications FGA côté serveur depuis des services backend