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

# MastraAuthOkta 및 MastraRBACokta 클래스

## MastraAuthOkta 클래스

`MastraAuthOkta` 클래스는 Okta를 사용하여 Mastra 인증을 제공합니다. 암호화된 세션 쿠키를 사용하는 OAuth 2.0 / OIDC 로그인 흐름을 구현하며, `auth` 옵션을 통해 Mastra 서버와 통합됩니다.

### 사용예

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

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthOkta({
      domain: process.env.OKTA_DOMAIN,
      clientId: process.env.OKTA_CLIENT_ID,
      clientSecret: process.env.OKTA_CLIENT_SECRET,
      redirectUri: process.env.OKTA_REDIRECT_URI,
    }),
  },
})
```

> **노트:** 필수 환경 변수가 설정되어 있으면 생성자 매개변수를 생략할 수 있습니다. 이 경우 인수 없이 `new MastraAuthOkta()`를 사용하세요.

### 생성자 매개변수

**domain** (`string`): Okta 도메인입니다(예: dev-123456.okta.com). 발급자 URL과 API 엔드포인트를 구성하는 데 사용됩니다. (Default: `process.env.OKTA_DOMAIN`)

**clientId** (`string`): Okta 애플리케이션의 OAuth 클라이언트 ID입니다. (Default: `process.env.OKTA_CLIENT_ID`)

**clientSecret** (`string`): OAuth 클라이언트 시크릿입니다. SSO 인증 코드 흐름에 필요합니다. (Default: `process.env.OKTA_CLIENT_SECRET`)

**issuer** (`string`): 토큰 발급자 URL입니다. 사용자 지정 인증 서버를 사용하는 경우 이 값을 재정의하세요. (Default: `` `https://{domain}/oauth2/default` ``)

**redirectUri** (`string`): SSO 콜백의 OAuth 리디렉션 URI입니다. Okta 애플리케이션에 구성된 리디렉션 URI와 일치해야 합니다. (Default: `process.env.OKTA_REDIRECT_URI`)

**scopes** (`string[]`): 로그인 흐름 중 요청할 OAuth 범위입니다. (Default: `['openid', 'profile', 'email', 'groups']`)

**apiToken** (`string`): Users API를 통한 사용자 조회용 Okta API 토큰입니다. getUser()가 ID로 사용자 데이터를 반환하려면 필요합니다. (Default: `process.env.OKTA_API_TOKEN`)

**session** (`OktaSessionOptions`): 세션 쿠키 구성입니다.

**session.cookieName** (`string`): 세션 쿠키의 이름입니다.

**session.cookieMaxAge** (`number`): 초 단위의 쿠키 최대 수명입니다.

**session.cookiePassword** (`string`): 세션 쿠키를 암호화하기 위한 비밀번호입니다. 32자 이상이어야 합니다. 설정하지 않으면 재시작 후 유지되지 않는 자동 생성 값이 사용됩니다.

**session.secureCookies** (`boolean`): 세션 쿠키에 Secure 플래그를 설정합니다.

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

### 환경변수

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

**OKTA\_DOMAIN** (`string`): Okta 도메인입니다(예: dev-123456.okta.com). Okta 관리 콘솔에서 확인할 수 있습니다.

**OKTA\_CLIENT\_ID** (`string`): Okta 애플리케이션의 OAuth 클라이언트 ID입니다.

**OKTA\_CLIENT\_SECRET** (`string`): Okta 애플리케이션의 OAuth 클라이언트 시크릿입니다.

**OKTA\_ISSUER** (`string`): 토큰 발급자 URL입니다. 설정하지 않으면 기본값은 https\://{domain}/oauth2/default입니다.

**OKTA\_REDIRECT\_URI** (`string`): SSO 콜백의 OAuth 리디렉션 URI입니다.

**OKTA\_COOKIE\_PASSWORD** (`string`): 세션 쿠키를 암호화하기 위한 비밀번호입니다. 32자 이상이어야 합니다.

**OKTA\_API\_TOKEN** (`string`): 사용자 조회 및 RBAC 그룹 확인을 위한 Okta API 토큰입니다.

### 인증 흐름

`MastraAuthOkta`다음 순서로 요청을 인증합니다.

1. **세션 쿠키**: 암호화된 세션 쿠키를 읽고 해독합니다. 세션이 유효하고 만료되지 않은 경우 사용자가 인증됩니다.
2. **JWT 대체**: 세션 쿠키가 없으면`Authorization` header token against Okta's JWKS endpoint.

인증 후 `authorizeUser`는 사용자에게 유효한 `oktaId`가 있는지 확인합니다. 추가 로직을 구현하려면 사용자 지정 `authorizeUser` 함수를 제공하세요.

### `OktaUser`유형

`OktaUser` 타입은 기본 `EEUser` 인터페이스를 Okta 전용 필드로 확장합니다.

**id** (`string`): 사용자 식별자입니다(sub 클레임에 매핑됨).

**oktaId** (`string`): Okta 사용자 ID입니다(id와 동일).

**email** (`string`): 사용자 이메일 주소입니다.

**name** (`string`): 토큰 클레임으로 구성된 사용자 표시 이름입니다.

**avatarUrl** (`string`): 사용자 프로필 사진의 URL입니다.

**groups** (`string[]`): 사용자가 속한 Okta 그룹이며 groups 클레임에서 채워집니다.

## MastraRBACOkta 클래스

`MastraRBACOkta` 클래스는 Okta 그룹을 Mastra 권한에 매핑합니다. Okta API에서 사용자 그룹을 가져와 구성 가능한 역할 매핑에 따라 확인합니다. `MastraAuthOkta` 또는 다른 인증 Provider와 함께 사용하세요.

> **노트:** RBAC에는 유효한 Enterprise Edition 라이선스가 필요합니다. 개발 중에는 라이선스 없이 작동하므로 로컬에서 사용해 볼 수 있지만 프로덕션에는 라이선스가 필요합니다. 자세한 내용은 [영업팀에 문의](https://mastra.ai/contact)하세요.

### 사용예

인증 Provider의 `rbac` 옵션에 `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: [],
      },
    }),
  },
})
```

다른 인증 Provider와 함께 Okta RBAC를 사용하려면 다른 Provider의 사용자 객체에서 Okta 사용자 ID를 확인하는 `getUserId` 함수를 전달하세요.

```typescript
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: [],
      },
    }),
  },
})
```

### 생성자 매개변수

**roleMapping** (`RoleMapping`): Okta 그룹 이름을 Mastra 권한 문자열 배열에 매핑합니다. 어떤 그룹과도 일치하지 않는 사용자에게 권한을 할당하려면 '\_default'를 사용하세요. '\*'(전체 액세스), 'agents:\*'(모든 Agent 작업)와 같은 와일드카드를 지원합니다.

**domain** (`string`): Okta 도메인입니다. Okta 관리 SDK를 초기화하는 데 사용됩니다. (Default: `process.env.OKTA_DOMAIN`)

**apiToken** (`string`): 관리 SDK용 Okta API 토큰입니다. Okta API에서 사용자 그룹을 가져오는 데 필요합니다. (Default: `process.env.OKTA_API_TOKEN`)

**getUserId** (`(user: unknown) => string | undefined`): 사용자 객체에서 Okta 사용자 ID를 추출합니다. Okta RBAC를 다른 인증 Provider와 결합할 때 사용하세요. 제공하지 않으면 사용자 객체의 oktaId 또는 id를 대신 사용합니다.

**cache** (`PermissionCacheOptions`): 그룹 조회용 LRU 캐시를 구성합니다.

**cache.maxSize** (`number`): 캐시할 수 있는 최대 사용자 수입니다.

**cache.ttlMs** (`number`): 밀리초 단위의 유효 기간입니다.