MastraAuthWorkos 클래스

그만큼MastraAuthWorkos클래스는 WorkOS를 사용하여 Mastra에 대한 인증을 제공합니다. WorkOS 액세스 토큰을 사용하여 들어오는 요청을 확인하고auth옵션.

사용예

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,
    }),
  },
})

노트

필수 환경 변수(WORKOS_API_KEY 및 WORKOS_CLIENT_ID)가 설정되어 있습니다. 이 경우 인수 없이 new MastraAuthWorkos()를 사용하세요.

생성자 매개변수

apiKey?:

string

= process.env.WORKOS_API_KEY

WorkOS API 키입니다. 사용자 검증 및 조직 관리를 위해 WorkOS API에 인증하는 데 사용됩니다.

clientId?:

string

= process.env.WORKOS_CLIENT_ID

WorkOS Client ID입니다. 인증 코드를 액세스 토큰으로 교환할 때 애플리케이션을 식별합니다.

name?:

string

= "workos"

인증 Provider 인스턴스의 사용자 지정 이름입니다.

redirectUri?:

string

= process.env.WORKOS_REDIRECT_URI

WorkOS AuthKit에서 사용하는 OAuth 리디렉션 URI입니다. 기본 제공 WorkOS 로그인 흐름을 사용할 때 설정하세요.

fetchMemberships?:

boolean

= false

인증 중 조직 멤버십을 불러옵니다. MastraFGAWorkos를 사용할 때 FGA 검사가 올바른 조직 멤버십 ID를 확인할 수 있도록 이 값을 true로 설정하세요.

trustJwtClaims?:

boolean

= false

workos.userManagement.getUser()가 적용되지 않는 경우에도 검증된 전달자 토큰 클레임을 신뢰하여 WorkOSUser를 구성합니다. WorkOS 사용자 지정 JWT 템플릿을 기반으로 하는 서비스 계정 또는 머신 간 토큰에 사용하세요.

jwtClaims?:

{ userId?: string; workosId?: string; email?: string; name?: string; organizationId?: string; organizationMembershipId?: string }

검증된 전달자 JWT 클레임을 인증된 WorkOSUser에 매핑합니다. organizationMembershipId 또는 기타 FGA 전용 클레임을 포함하는 사용자 지정 JWT 템플릿에 유용합니다.

환경변수

생성자 옵션이 제공되지 않으면 다음 환경 변수가 자동으로 사용됩니다.

WORKOS_API_KEY?:

string

WorkOS API 키입니다. WorkOS Dashboard의 API Keys에서 확인할 수 있습니다.

WORKOS_CLIENT_ID?:

string

WorkOS Client ID입니다. WorkOS Dashboard의 Applications에서 확인할 수 있습니다.

WORKOS_REDIRECT_URI?:

string

기본 제공 세션 기반 흐름을 사용할 때 WorkOS AuthKit에서 사용하는 OAuth 리디렉션 URI입니다.

기본 인증 동작

기본적으로 MastraAuthWorkos는 확인된 사용자 객체에 id와 workosId가 모두 포함된 인증된 모든 WorkOS 사용자를 승인합니다.

1. 토큰 검증: 액세스 토큰이 WorkOS로 확인되어 유효하고 만료되지 않았는지 확인합니다.
2. 사용자 검색: 검증된 토큰에서 사용자 정보를 추출합니다.
3. 승인 결정: 확인된 사용자가 필수 식별자를 포함하는 경우 액세스 권한이 부여됩니다.

MastraAuthWorkos기본적으로 역할 게이트가 아닌 인증 공급자 역할을 합니다.

FGA 회원 로딩 중

MastraFGAWorkos를 사용할 때는 fetchMemberships: true를 설정하세요. 그러면 인증 중 사용자의 WorkOS 조직 멤버십을 불러와 FGA 검사가 올바른 조직 멤버십 ID를 확인할 수 있습니다. fetchMemberships가 false이면 Mastra는 인증된 각 요청에서 추가 WorkOS listOrganizationMemberships() 호출을 건너뜁니다.

서비스 토큰 및 JWT 클레임

WorkOS JWT 템플릿에 사용자 지정 클레임이 포함된 경우 이를 인증된 클레임에 직접 매핑할 수 있습니다.WorkOSUser.

src/mastra/auth.ts

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

const auth = 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',
  },
})

trustJwtClaims를 활성화하면 getUser()가 적절한 조회 경로가 아니더라도 Mastra에서 서비스 주체의 검증된 전달자 토큰을 인증할 수 있습니다. 머신 간 흐름의 FGA 검사에 미리 확인된 organizationMembershipId 값을 전달할 때 권장되는 방식입니다.

맞춤 인증

더 엄격한 권한 부여가 필요하면 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'
  }
}

WorkOS 사용자 유형

authorizeUser() 및 기타 WorkOS 인증 훅에서 사용할 수 있는 WorkOSUser 타입에는 Mastra의 정규화된 사용자 필드와 WorkOS 전용 메타데이터가 포함됩니다. WorkOS에서는 관리자가 사용자 지정 JWT 템플릿을 설정할 수도 있으므로 정확한 구조는 구성에 따라 달라질 수 있습니다. 다음 예시는 WorkOS 기반 사용자 객체의 형태를 보여 줍니다.

{
  'urn:myapp:full_name': 'John Doe',
  'urn:myapp:email': 'john.doe@example.com',
  'urn:myapp:organization_tier': 'bronze',
  'urn:myapp:user_language': 'en',
  'urn:myapp:organization_domain': 'example.com',
  iss: 'https://api.workos.com/user_management/client_01ABC123DEF456GHI789JKL012',
  sub: 'user_01XYZ789ABC123DEF456GHI012',
  sid: 'session_01PQR456STU789VWX012YZA345',
  jti: '01MNO678PQR901STU234VWX567',
  org_id: 'org_01DEF234GHI567JKL890MNO123',
  role: 'member',
  roles: [ 'member' ],
  permissions: [],
  exp: 1758290589,
  iat: 1758290289
}

urn:myapp: 접두사가 있는 속성은 WorkOS JWT 템플릿에 구성된 사용자 지정 클레임입니다. 표준 JWT 클레임에는 sub(사용자 ID), iss(발급자), exp(만료)가 있으며, WorkOS 전용 클레임에는 org_id, role, roles 등이 있습니다.

관련된

MastraAuthWorkos 클래스