옥타

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

전제조건

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

1. 다음에서 Okta 계정을 만드세요.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

npm install @mastra/auth-okta

pnpm

pnpm add @mastra/auth-okta

Yarn

yarn add @mastra/auth-okta

Bun

bun add @mastra/auth-okta

사용 예

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

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

src/mastra/index.ts

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

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

RBAC로 인증

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

src/mastra/index.ts

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 함수를 전달하세요.

src/mastra/index.ts

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를 참조하세요.

역할 매핑

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

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 자격 증명을 활성화하세요.

src/mastra/index.ts

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

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

lib/mastra-client.ts

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

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

무기명 토큰

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

lib/mastra-client.ts

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를 참조하세요.

인증된 요청 만들기

MastraClient

src/api/agents.ts

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

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

cURL

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 그룹 이름과 정확히 일치하는지 확인하세요.