WorkOS

그만큼@mastra/auth-workos패키지는 WorkOS를 사용하여 Mastra에 대한 인증을 제공합니다. WorkOS 액세스 토큰을 사용하여 들어오는 요청을 확인하고auth옵션.

전제조건

이 예에서는 WorkOS 인증을 사용합니다. 다음을 확인하세요.

1. WorkOS 계정을 만드세요.workos.com
2. WorkOS 대시보드에서 애플리케이션 설정
3. 리디렉션 URI 및 허용되는 원본 구성
4. 필요에 따라 조직을 설정하고 사용자 역할을 구성합니다.

.env

WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...

노트

WorkOS 대시보드의 API 키 및 애플리케이션에서 각각 API 키와 클라이언트 ID를 찾을 수 있습니다.

플랫폼별 설정 지침은 WorkOS 문서를 참조하세요.

설치

MastraAuthWorkos 클래스를 사용하기 전에 @mastra/auth-workos 패키지를 설치해야 합니다.

npm

npm install @mastra/auth-workos@latest

pnpm

pnpm add @mastra/auth-workos@latest

Yarn

yarn add @mastra/auth-workos@latest

Bun

bun add @mastra/auth-workos@latest

사용 예

환경 변수를 사용한 기본 사용법

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos(),
  },
})

맞춤 구성

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthWorkos } from '@mastra/auth-workos'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthWorkos({
      apiKey: process.env.WORKOS_API_KEY,
      clientId: process.env.WORKOS_CLIENT_ID,
    }),
  },
})

구성

기본 승인

기본적으로 MastraAuthWorkos는 인증된 모든 WorkOS 사용자에게 액세스 권한을 부여합니다. 확인된 사용자 객체에 Mastra 사용자 ID와 WorkOS 사용자 ID가 모두 포함되어 있으면 권한 부여 검사에 성공합니다.

FGA 회원 로딩 중

MastraFGAWorkos를 사용할 때는 fetchMemberships: true를 설정하세요. 그러면 인증 Provider가 인증 중에 사용자의 WorkOS 조직 멤버십을 로드하므로 FGA 검사에서 올바른 조직 멤버십 ID를 확인할 수 있습니다.

src/mastra/auth.ts

import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  fetchMemberships: true,
})

const workosFga = new MastraFGAWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

fetchMemberships가 false이면 Mastra는 인증된 각 요청에서 추가 WorkOS listOrganizationMemberships() 호출을 건너뜁니다.

서비스 토큰 및 사용자 정의 JWT 템플릿

머신 간 또는 서비스 계정 액세스의 경우 WorkOS 사용자 지정 JWT 템플릿에서 검증된 Bearer 토큰 클레임을 신뢰하도록 MastraAuthWorkos를 구성할 수 있습니다.

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'

const workosAuth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri: process.env.WORKOS_REDIRECT_URI,
  trustJwtClaims: true,
  jwtClaims: {
    organizationId: 'org_id',
    organizationMembershipId: 'urn:mastra:organization_membership_id',
  },
})

이는 JWT 템플릿에 organizationMembershipId, 테넌트 ID 또는 서비스 주체 식별자와 같이 Mastra에 필요한 정확한 FGA 컨텍스트가 이미 포함된 경우 유용합니다. trustJwtClaims가 활성화되면 Bearer 토큰이 workos.userManagement.getUser()를 거치도록 설계되지 않은 경우 Mastra가 검증된 해당 클레임을 대체 값으로 사용할 수 있습니다.

맞춤 인증

더 엄격한 권한 부여가 필요하다면 MastraAuthWorkos를 서브클래싱하고 authorizeUser()를 재정의하세요.

src/mastra/auth.ts

import { MastraAuthWorkos } from '@mastra/auth-workos'
import type { HonoRequest } from 'hono'

class AdminOnlyWorkosAuth extends MastraAuthWorkos {
  async authorizeUser(user: any, _request: HonoRequest): Promise<boolean> {
    return user?.metadata?.role === 'admin'
  }
}

const workosAuth = new AdminOnlyWorkosAuth({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
})

사용 가능한 모든 구성 옵션은 MastraAuthWorkos를 참조하세요.

클라이언트 측 설정

WorkOS 인증을 사용하는 경우 WorkOS 인증 흐름을 구현하여 액세스 토큰에 대한 인증 코드를 교환한 다음 Mastra 요청에 해당 토큰을 사용해야 합니다.

WorkOS SDK 설치

먼저 애플리케이션에 WorkOS SDK를 설치합니다.

npm

npm install @workos-inc/node

pnpm

pnpm add @workos-inc/node

Yarn

yarn add @workos-inc/node

Bun

bun add @workos-inc/node

액세스 토큰을 위한 코드 교환

사용자가 WorkOS 인증 흐름을 완료하고 인증 코드를 반환한 후 이를 액세스 토큰으로 교환합니다.

lib/auth.ts

import { WorkOS } from '@workos-inc/node'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const authenticateWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  return authenticationResponse.accessToken
}

노트

더 많은 인증 방식과 구성 옵션은 WorkOS User Management 문서를 참조하세요.

구성MastraClient

auth가 활성화되면 MastraClient로 보내는 모든 요청의 Authorization 헤더에 유효한 WorkOS 액세스 토큰을 포함해야 합니다.

lib/mastra/mastra-client.ts

import { MastraClient } from '@mastra/client-js'

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'https://<mastra-api-url>',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}

정보

Authorization 헤더의 액세스 토큰 앞에는 Bearer를 붙여야 합니다. 더 많은 구성 옵션은 Mastra Client SDK를 참조하세요.

인증된 요청 만들기

WorkOS 액세스 토큰으로 MastraClient를 구성하면 인증된 요청을 보낼 수 있습니다.

React

src/api/agents.ts

import { WorkOS } from '@workos-inc/node'
import { MastraClient } from '@mastra/client-js'

const workos = new WorkOS(process.env.WORKOS_API_KEY)

export const callMastraWithWorkos = async (code: string, clientId: string) => {
  const authenticationResponse = await workos.userManagement.authenticateWithCode({
    code,
    clientId,
  })

  const token = authenticationResponse.accessToken

  const mastra = new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${token}`,
    },
  })

  const weatherAgent = mastra.getAgent('weatherAgent')
  const response = await weatherAgent.generate("What's the weather like in Nairobi")

  return response.text
}

cURL

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-workos-access-token>" \
  -d '{
    "messages": "Weather in London"
  }'