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

# 옥타

그만큼`@mastra/auth-okta`패키지는 Okta를 사용하여 Mastra에 대한 인증 및 역할 기반 액세스 제어를 제공합니다. 암호화된 세션 쿠키를 사용하여 OAuth 2.0/OIDC 로그인 흐름을 지원하고 Okta 그룹을 Mastra 권한에 매핑합니다.

## 전제조건

이 가이드에서는 Okta 인증을 사용합니다. 다음을 확인하세요.

1. 다음에서 Okta 계정을 만드세요.[okta.com](https://www.okta.com/)
2. Okta 관리 콘솔에서 OAuth 애플리케이션 설정(웹 앱, 인증 코드 부여)
3. 애플리케이션의 로그인 리디렉션 URI에 리디렉션 URI를 추가합니다.
4. API 토큰 생성(RBAC에 필요)

환경 변수가 설정되어 있는지 확인하세요.

```env
OKTA_DOMAIN=dev-123456.okta.com
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_REDIRECT_URI=http://localhost:4111/api/auth/callback
OKTA_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
OKTA_API_TOKEN=your-api-token
```

> **노트:** `OKTA_COOKIE_PASSWORD`세션 쿠키를 암호화합니다. 생략하면 서버를 다시 시작해도 유지되지 않는 자동 생성 값이 사용됩니다. 프로덕션을 위해 명시적으로 설정합니다.
>
> `OKTA_API_TOKEN`은 Okta 그룹을 권한에 매핑하기 위해 `MastraRBACOkta`를 사용할 때만 필요합니다.

## 설치

**npm**:

```bash
npm install @mastra/auth-okta
```

**pnpm**:

```bash
pnpm add @mastra/auth-okta
```

**Yarn**:

```bash
yarn add @mastra/auth-okta
```

**Bun**:

```bash
bun add @mastra/auth-okta
```

## 사용 예

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

위의 환경 변수를 설정하면 모든 생성자 매개변수는 선택사항입니다.

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta } from '@mastra/auth-okta'

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

### RBAC로 인증

Okta 그룹을 Mastra 권한에 매핑하려면 `MastraRBACOkta`를 추가하세요.

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    rbac: new MastraRBACOkta({
      roleMapping: {
        Admin: ['*'],
        Engineering: ['agents:*', 'workflows:*', 'tools:*'],
        Viewer: ['agents:read', 'workflows:read'],
        _default: [], // users with unmapped groups get no permissions
      },
    }),
  },
})
```

### 공급자 간 사용

로그인에는 다른 인증 Provider(Auth0, Clerk 등)를 사용하고 RBAC에는 Okta를 사용하세요. 다른 Provider의 사용자 객체에서 Okta 사용자 ID를 확인하려면 `getUserId` 함수를 전달하세요.

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
import { MastraRBACOkta } from '@mastra/auth-okta'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0(),
    rbac: new MastraRBACOkta({
      getUserId: user => user.metadata?.oktaUserId || user.email,
      roleMapping: {
        Engineering: ['agents:*', 'workflows:*'],
        Admin: ['*'],
        _default: [],
      },
    }),
  },
})
```

> **노트:** 공급자 간에 사용자를 연결하려면 Okta 사용자 ID를 다른 공급자의 사용자 메타데이터에 저장하세요. Mastra는 이 ID를 사용하여 Okta에서 그룹을 가져옵니다.

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

## 역할 매핑

`roleMapping` 옵션은 Okta 그룹 이름을 Mastra 권한 문자열 배열에 매핑합니다. 권한은 `resource:action` 패턴을 따르며 와일드카드를 지원합니다.

```typescript
const rbac = new MastraRBACOkta({
  roleMapping: {
    // full access to everything
    Admin: ['*'],

    // full access to agents and workflows
    Engineering: ['agents:*', 'workflows:*'],

    // read-only access
    Viewer: ['agents:read', 'workflows:read'],

    // users whose groups don't match any key above
    _default: [],
  },
})
```

`_default` 키는 다른 어떤 키와도 일치하지 않는 Okta 그룹에 속한 사용자에게 권한을 할당합니다.

## 클라이언트 측 설정

인증이 활성화되면 Mastra 경로에 대한 요청에 인증이 필요합니다. `MastraAuthOkta`는 SSO를 사용하므로 사용자는 Okta에서 호스팅하는 로그인 페이지를 통해 인증합니다. 로그인 후 암호화된 세션 쿠키가 자동으로 설정됩니다.

### 쿠키 세션(권장)

교차 출처 요청의 경우(예: `:3000`의 프런트엔드에서 `:4111`의 Mastra를 호출하는 경우) Mastra 서버에서 CORS 자격 증명을 활성화하세요.

```typescript
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta(),
    cors: {
      origin: 'http://localhost:3000',
      credentials: true,
    },
  },
})
```

자격 증명을 포함하도록 클라이언트를 구성합니다.

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

export const mastraClient = new MastraClient({
  baseUrl: 'http://localhost:4111',
  credentials: 'include',
})
```

### 무기명 토큰

Okta 액세스 토큰을 Bearer 토큰으로 전달할 수도 있습니다. 토큰은 Okta의 JWKS 엔드포인트에 대해 확인됩니다.

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

export const createMastraClient = (accessToken: string) => {
  return new MastraClient({
    baseUrl: 'http://localhost:4111',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  })
}
```

더 많은 구성 옵션은 [Mastra Client SDK](https://mastra.zisheng.pro/ko/docs/server/mastra-client)를 참조하세요.

### 인증된 요청 만들기

**MastraClient**:

```typescript
import { mastraClient } from '../lib/mastra-client'

const agent = mastraClient.getAgent('weatherAgent')
const response = await agent.generate('Weather in London')
console.log(response)
```

**cURL**:

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

## 문제 해결

- **모든 요청에 401 발생**: Okta 도메인, 클라이언트 ID, 클라이언트 비밀번호가 올바른지 확인하세요. Okta 애플리케이션의 리디렉션 URI가 `OKTA_REDIRECT_URI`와 일치하는지 확인하세요.
- **교차 출처로 쿠키가 전송되지 않음**: `MastraClient`에서 `credentials: "include"`를 설정하고, 프런트엔드 출처 및 `credentials: true`로 `server.cors`를 구성하세요.
- **다시 시작하면 세션이 손실됨**: `OKTA_COOKIE_PASSWORD`를 32자 이상의 안정적인 값으로 설정하세요. 설정하지 않으면 다시 시작할 때마다 변경되는 자동 생성 키가 사용됩니다.
- **RBAC가 빈 권한을 반환함**: `OKTA_API_TOKEN`이 설정되어 있고 토큰에 사용자 그룹을 나열할 권한이 있는지 확인하세요. `roleMapping`의 그룹 이름이 Okta 그룹 이름과 정확히 일치하는지 확인하세요.