IFGA 제공자

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

Mastra가 FGA를 시행하는 개념, 구성 및 수명 주기 지점은 다음을 참조하세요.Fine-grained authorization.

사용예

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

src/mastra/fga.ts

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는 적용 지점에서 이를 호출합니다. 보고: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의 권위 있는 권한 부여를 확인하세요. 시스템 행위자를 참조하세요.

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

= false

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

auditProtectedRoutes?:

boolean | 'warn' | 'error'

= false

기본 제공 FGA 메타데이터가 없는 보호 경로를 감사합니다. 시작 경고를 기록하려면 true 또는 'warn'을, 시작에 실패하게 하려면 'error'를, 비활성화하려면 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으로 노출합니다.

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.

관련된

• 세분화된 승인
• 시스템 액터
• WorkOS 인증