> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# IFGAProvider

L’interface `IFGAProvider` définit un Provider d’autorisation granulaire (FGA). Mastra l’appelle pour déterminer si un utilisateur ou un acteur système peut exercer une permission sur une ressource donnée. Implémentez-la pour connecter Mastra à un backend FGA tel que WorkOS Authorization.

Pour découvrir les concepts, la configuration et les étapes du cycle de vie auxquelles Mastra applique FGA, consultez la page [Autorisation granulaire](https://mastra.zisheng.pro/fr/docs/server/auth/fga).

## Exemple d’utilisation

L’exemple suivant implémente un Provider minimal. `require` lève une erreur pour refuser l’accès, tandis que `check` renvoie un booléen.

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { FGACheckParams, IFGAProvider, MastraFGAPermissionInput } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  async check(user: any, params: FGACheckParams): Promise<boolean> {
    // Your authorization logic.
    return true
  }

  async require(user: any, params: FGACheckParams): Promise<void> {
    if (!(await this.check(user, params))) {
      throw new FGADeniedError(user, params.resource, params.permission)
    }
  }

  async filterAccessible<T extends { id: string }>(
    user: any,
    resources: T[],
    resourceType: string,
    permission: MastraFGAPermissionInput,
  ): Promise<T[]> {
    return resources
  }
}
```

## Méthodes

### `check(user, params)`

Indique si `user` possède la permission sur la ressource. Utilisez cette méthode pour les vérifications qui ne lèvent pas d’erreur, comme le filtrage ou les interfaces conditionnelles.

Renvoie : `Promise<boolean>`

### `require(user, params)`

Lève `FGADeniedError` lorsque `user` ne possède pas la permission. Mastra appelle cette méthode à ses [points d’application](https://mastra.zisheng.pro/fr/docs/server/auth/fga).

Renvoie : `Promise<void>`

### `filterAccessible(user, resources, resourceType, permission)`

Renvoie le sous-ensemble de `resources` auquel `user` peut accéder avec `permission`.

Renvoie : `Promise<T[]>`

### `requireActor(actor, params)`

Autorise un acteur système qui n’est pas un utilisateur, tel qu’un Agent autonome ou planifié. Facultatif.

Les acteurs système contournent le chemin `require()` centré sur l’utilisateur. Implémentez donc `requireActor` afin d’appliquer pour eux le principe du moindre privilège à chaque Agent. Levez `FGADeniedError` pour refuser l’accès. Lorsqu’un Provider n’implémente pas `requireActor`, Mastra conserve le contournement destiné aux acteurs de confiance, c’est-à-dire l’autorisation après vérification de la portée du tenant. L’ajout de cette méthode reste ainsi rétrocompatible.

Traitez `actor.permissions` comme un claim non fiable. Résolvez les autorisations faisant foi de l’Agent à partir d’une source de confiance indexée par `actor.agentId`, au lieu de vous fier aux valeurs intégrées. Consultez la section [Acteurs système](https://mastra.zisheng.pro/fr/docs/server/auth/fga).

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'
import type { ActorSignal, FGACheckParams, IFGAProvider } from '@mastra/core/auth/ee'

class MyFGAProvider implements IFGAProvider {
  // ...check, require, filterAccessible...

  async requireActor(actor: ActorSignal, params: FGACheckParams): Promise<void> {
    const agentId = actor === true ? undefined : actor.agentId
    // Resolve the agent's authoritative grants from a trusted source keyed by agentId.
    const granted = await this.grantsForAgent(agentId)
    const required = Array.isArray(params.permission) ? params.permission : [params.permission]
    if (!required.some(permission => granted.includes(permission))) {
      throw new FGADeniedError(null, params.resource, params.permission)
    }
  }
}
```

Renvoie : `Promise<void>`

## Propriétés de configuration

Des propriétés facultatives contrôlent la couverture des routes et la validation au démarrage.

**requireForProtectedRoutes** (`boolean`): Lorsque la valeur est true, les routes protégées dépourvues de métadonnées FGA au niveau de la route ou de sortie du résolveur sont refusées au lieu d’être autorisées. (Default: `false`)

**auditProtectedRoutes** (`boolean | 'warn' | 'error'`): Audite les routes protégées qui ne possèdent pas de métadonnées FGA intégrées. Utilisez true ou 'warn' pour consigner un avertissement au démarrage, 'error' pour faire échouer le démarrage ou false pour désactiver l’audit. (Default: `false`)

**resolveRouteFGA** (`FGARouteResolver`): Déduit le type et l’ID de la ressource, ainsi que la permission, à partir de la route, des paramètres analysés et du contexte de requête.

**validatePermissions** (`(permissions: MastraFGAPermissionInput[]) => void | Promise<void>`): Validation au démarrage des correspondances de permissions propres au Provider. Lève une erreur lorsqu’une permission que Mastra peut émettre n’est pas associée.

## Paramètres

Argument `params` transmis à `check`, `require` et `requireActor`.

**resource** (`{ type: string; id: string }`): Ressource faisant l’objet de l’accès.

**permission** (`MastraFGAPermissionInput | MastraFGAPermissionInput[]`): Permission(s) vérifiée(s). Lorsqu’un tableau est fourni, l’acteur doit posséder au moins l’une des permissions répertoriées.

**context** (`FGACheckContext`): Contexte propre au Provider pour la résolution de la ressource, notamment le resourceId propriétaire, le contexte de requête et les métadonnées de l’action.

## `ActorSignal`

Identifie un appel effectué par un acteur de confiance qui n’est pas un utilisateur, plutôt que par un utilisateur final authentifié. Il s’agit soit de `true`, forme abrégée du système anonyme, soit d’un objet qui nomme l’Agent agissant et contient les autorisations qu’un Provider peut appliquer.

**actorKind** (`'system'`): Identifie la forme objet du signal.

**agentId** (`string`): Identité de l’Agent système agissant. Contrairement à la ressource vérifiée, qui constitue la cible, cette valeur nomme l’acteur lui-même afin qu’un Provider puisse appliquer le principe du moindre privilège pour chaque Agent.

**permissions** (`MastraFGAPermissionInput[]`): Autorisations revendiquées pour cet acteur. Il s’agit d’une indication autodéclarée et non fiable ; un Provider qui applique réellement le principe du moindre privilège résout les autorisations faisant foi de l’Agent à partir d’une source de confiance indexée par agentId, au lieu de se fier à ces valeurs.

**scope** (`Record<string, string>`): Portée supplémentaire propre au Provider pour l’acteur, par exemple le tenant ou l’environnement.

**sourceWorkflow** (`string`): Nom du Workflow qui a démarré l’exécution de l’acteur, le cas échéant.

## `FGADeniedError`

Erreur levée lorsqu’une vérification d’autorisation est refusée. `require` et `requireActor` la lèvent pour refuser l’accès, et Mastra la présente comme une réponse HTTP `403`.

```typescript
import { FGADeniedError } from '@mastra/core/auth/ee'

throw new FGADeniedError(user, { type: 'agent', id: 'reporter' }, 'agents:execute')
// Optional fourth argument: a reason string included in the error message.
```

## Voir aussi

- [Autorisation granulaire](https://mastra.zisheng.pro/fr/docs/server/auth/fga)
- [Acteurs système](https://mastra.zisheng.pro/fr/docs/server/auth/fga)
- [Authentification WorkOS](https://mastra.zisheng.pro/fr/reference/auth/workos)