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

# MastraAuthWorkos 클래스

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

## 사용예

```typescript
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`): WorkOS API 키입니다. 사용자 검증 및 조직 관리를 위해 WorkOS API에 인증하는 데 사용됩니다. (Default: `process.env.WORKOS_API_KEY`)

**clientId** (`string`): WorkOS Client ID입니다. 인증 코드를 액세스 토큰으로 교환할 때 애플리케이션을 식별합니다. (Default: `process.env.WORKOS_CLIENT_ID`)

**name** (`string`): 인증 Provider 인스턴스의 사용자 지정 이름입니다. (Default: `"workos"`)

**redirectUri** (`string`): WorkOS AuthKit에서 사용하는 OAuth 리디렉션 URI입니다. 기본 제공 WorkOS 로그인 흐름을 사용할 때 설정하세요. (Default: `process.env.WORKOS_REDIRECT_URI`)

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

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

**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`.

```typescript
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()`를 재정의하세요.

```typescript
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 기반 사용자 객체의 형태를 보여 줍니다.

```javascript
{
  '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 클래스](https://mastra.zisheng.pro/ko/docs/server/auth/workos)