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

# IFGA 제공자

그만큼`IFGAProvider`인터페이스는 FGA(Fine-grained Authorization) 제공자를 정의합니다. Mastra는 이를 호출하여 사용자 또는 시스템 행위자가 특정 리소스에 대한 권한을 수행할 수 있는지 여부를 결정합니다. WorkOS 인증과 같은 FGA 백엔드에 Mastra를 연결하려면 이를 구현하세요.

Mastra가 FGA를 시행하는 개념, 구성 및 수명 주기 지점은 다음을 참조하세요.[Fine-grained authorization](https://mastra.zisheng.pro/ko/docs/server/auth/fga).

## 사용예

다음 예제에서는 최소 Provider를 구현합니다. `require`는 거부할 때 예외를 발생시키고 `check`는 불리언을 반환합니다.

```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
  }
}
```

## 행동 양식

### `check(user, params)`

`user`가 리소스에 대한 권한을 보유하는지 반환합니다. 필터링이나 조건부 UI와 같이 예외를 발생시키지 않는 검사에 사용하세요. 보고:`Promise<boolean>`

### `require(user, params)`

`user`에게 권한이 없으면 `FGADeniedError`를 발생시킵니다. Mastra는 [적용 지점](https://mastra.zisheng.pro/ko/docs/server/auth/fga)에서 이를 호출합니다. 보고:`Promise<void>`

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

`user`가 `permission`으로 액세스할 수 있는 `resources`의 하위 집합을 반환합니다. 보고:`Promise<T[]>`

### `requireActor(actor, params)`

자율 또는 예약 Agent와 같은 비사용자 시스템 행위자에게 권한을 부여합니다. 선택 과목.

시스템 행위자는 사용자 중심의 `require()` 경로를 건너뛰므로, 이들에게 Agent별 최소 권한을 적용하려면 `requireActor`를 구현하세요. 거부하려면 `FGADeniedError`를 발생시키세요. Provider가 `requireActor`를 구현하지 않으면 Mastra는 신뢰할 수 있는 행위자 우회를 유지하므로(테넌트 범위 검사 후 허용) 메서드를 추가해도 이전 버전과 호환됩니다. `actor.permissions`를 신뢰할 수 없는 클레임으로 취급하세요. 인라인 값을 신뢰하지 말고 `actor.agentId`를 키로 사용하여 신뢰할 수 있는 소스에서 Agent의 권위 있는 권한 부여를 확인하세요. [시스템 행위자](https://mastra.zisheng.pro/ko/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)
    }
  }
}
```

보고:`Promise<void>`

## 구성 속성

선택적 속성은 경로 범위 및 시작 유효성 검사를 제어합니다.

**requireForProtectedRoutes** (`boolean`): true이면 경로 수준 FGA 메타데이터나 리졸버 출력이 없는 보호 경로를 통과시키지 않고 거부합니다. (Default: `false`)

**auditProtectedRoutes** (`boolean | 'warn' | 'error'`): 기본 제공 FGA 메타데이터가 없는 보호 경로를 감사합니다. 시작 경고를 기록하려면 true 또는 'warn'을, 시작에 실패하게 하려면 'error'를, 비활성화하려면 false를 사용하세요. (Default: `false`)

**resolveRouteFGA** (`FGARouteResolver`): 경로, 파싱된 매개변수 및 요청 컨텍스트에서 리소스 타입, 리소스 ID 및 권한을 도출합니다.

**validatePermissions** (`(permissions: MastraFGAPermissionInput[]) => void | Promise<void>`): Provider별 권한 매핑을 시작할 때 검증합니다. Mastra가 내보낼 수 있는 권한이 매핑되지 않았으면 예외를 발생시키세요.

## 매개변수

`check`, `require`, `requireActor`에 전달되는 `params` 인수입니다.

**resource** (`{ type: string; id: string }`): 액세스 중인 리소스입니다.

**permission** (`MastraFGAPermissionInput | MastraFGAPermissionInput[]`): 확인할 권한입니다. 배열을 제공하면 행위자는 나열된 권한 중 하나만 보유하면 됩니다.

**context** (`FGACheckContext`): 리소스 확인을 위한 Provider별 컨텍스트로, 소유하는 resourceId, 요청 컨텍스트 및 작업 메타데이터를 포함합니다.

## `ActorSignal`

인증된 최종 사용자가 아닌 신뢰할 수 있는 비사용자 행위자가 시작한 호출을 식별합니다. `true`(익명 시스템 축약형) 또는 실행 중인 Agent의 이름을 지정하고 Provider가 적용할 수 있는 권한 부여를 포함하는 객체입니다.

**actorKind** (`'system'`): 신호의 객체 형식임을 표시합니다.

**agentId** (`string`): 실행 중인 시스템 Agent의 ID입니다. 검사 리소스(대상)와 달리 행위자 자체를 지정하므로 Provider가 Agent별 최소 권한을 적용할 수 있습니다.

**permissions** (`MastraFGAPermissionInput[]`): 이 행위자에 대해 주장된 권한 부여입니다. 이는 신뢰할 수 없는 자체 주장 힌트입니다. 실제 최소 권한을 적용하는 Provider는 이 값을 신뢰하지 않고 agentId를 키로 사용하여 신뢰할 수 있는 소스에서 Agent의 권위 있는 권한 부여를 확인합니다.

**scope** (`Record<string, string>`): 행위자에 대한 추가 Provider별 범위입니다(예: 테넌트 또는 환경).

**sourceWorkflow** (`string`): 해당하는 경우 행위자 실행을 시작한 Workflow의 이름입니다.

## `FGADeniedError`

권한 부여 검사가 거부되면 발생합니다. `require`와 `requireActor`는 거부하기 위해 이를 발생시키며, Mastra는 이를 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.
```

## 관련된

- [세분화된 승인](https://mastra.zisheng.pro/ko/docs/server/auth/fga)
- [시스템 액터](https://mastra.zisheng.pro/ko/docs/server/auth/fga)
- [WorkOS 인증](https://mastra.zisheng.pro/ko/reference/auth/workos)