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

# WorkOS

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

## 전제조건

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

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

```env
WORKOS_API_KEY=sk_live_...
WORKOS_CLIENT_ID=client_...
```

> **노트:** WorkOS 대시보드의 API 키 및 애플리케이션에서 각각 API 키와 클라이언트 ID를 찾을 수 있습니다.
>
> 플랫폼별 설정 지침은 [WorkOS 문서](https://workos.com/docs)를 참조하세요.

## 설치

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

**npm**:

```bash
npm install @mastra/auth-workos@latest
```

**pnpm**:

```bash
pnpm add @mastra/auth-workos@latest
```

**Yarn**:

```bash
yarn add @mastra/auth-workos@latest
```

**Bun**:

```bash
bun add @mastra/auth-workos@latest
```

## 사용 예

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

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

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

### 맞춤 구성

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

## 구성

### 기본 승인

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

### FGA 회원 로딩 중

[`MastraFGAWorkos`](https://mastra.zisheng.pro/ko/docs/server/auth/fga)를 사용할 때는 `fetchMemberships: true`를 설정하세요. 그러면 인증 Provider가 인증 중에 사용자의 WorkOS 조직 멤버십을 로드하므로 FGA 검사에서 올바른 조직 멤버십 ID를 확인할 수 있습니다.

```typescript
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`를 구성할 수 있습니다.

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

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

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

사용 가능한 모든 구성 옵션은 [MastraAuthWorkos](https://mastra.zisheng.pro/ko/reference/auth/workos)를 참조하세요.

## 클라이언트 측 설정

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

### WorkOS SDK 설치

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

**npm**:

```bash
npm install @workos-inc/node
```

**pnpm**:

```bash
pnpm add @workos-inc/node
```

**Yarn**:

```bash
yarn add @workos-inc/node
```

**Bun**:

```bash
bun add @workos-inc/node
```

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

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

```typescript
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 문서](https://workos.com/docs/authkit/vanilla/nodejs)를 참조하세요.

## 구성`MastraClient`

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

```typescript
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](https://mastra.zisheng.pro/ko/docs/server/mastra-client)를 참조하세요.

### 인증된 요청 만들기

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

**React**:

```typescript
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**:

```bash
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"
  }'
```