본문으로 건너뛰기

MastraAuthOkta 및 MastraRBACokta 클래스

MastraAuthOkta 클래스
MastraAuthOkta 클래스에 대한 직접 링크

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

사용예
사용예에 대한 직접 링크

src/mastra/index.ts
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
= process.env.OKTA_DOMAIN
Okta 도메인입니다(예: dev-123456.okta.com). 발급자 URL과 API 엔드포인트를 구성하는 데 사용됩니다.

clientId?:

string
= process.env.OKTA_CLIENT_ID
Okta 애플리케이션의 OAuth 클라이언트 ID입니다.

clientSecret?:

string
= process.env.OKTA_CLIENT_SECRET
OAuth 클라이언트 시크릿입니다. SSO 인증 코드 흐름에 필요합니다.

issuer?:

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

redirectUri?:

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

scopes?:

string[]
= ['openid', 'profile', 'email', 'groups']
로그인 흐름 중 요청할 OAuth 범위입니다.

apiToken?:

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

session?:

OktaSessionOptions
세션 쿠키 구성입니다.
OktaSessionOptions

cookieName?:

string
세션 쿠키의 이름입니다.

cookieMaxAge?:

number
초 단위의 쿠키 최대 수명입니다.

cookiePassword?:

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

secureCookies?:

boolean
세션 쿠키에 Secure 플래그를 설정합니다.

name?:

string
= 'okta'
인증 Provider 인스턴스의 사용자 지정 이름입니다.

환경변수
환경변수에 대한 직접 링크

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

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-type에 대한 직접 링크

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

id:

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

oktaId:

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

email?:

string
사용자 이메일 주소입니다.

name?:

string
토큰 클레임으로 구성된 사용자 표시 이름입니다.

avatarUrl?:

string
사용자 프로필 사진의 URL입니다.

groups?:

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

MastraRBACOkta 클래스
MastraRBACOkta 클래스에 대한 직접 링크

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

노트

RBAC에는 유효한 Enterprise Edition 라이선스가 필요합니다. 개발 중에는 라이선스 없이 작동하므로 로컬에서 사용해 볼 수 있지만 프로덕션에는 라이선스가 필요합니다. 자세한 내용은 영업팀에 문의하세요.

사용예
사용예에 대한 직접 링크

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

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

src/mastra/index.ts
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
= process.env.OKTA_DOMAIN
Okta 도메인입니다. Okta 관리 SDK를 초기화하는 데 사용됩니다.

apiToken?:

string
= process.env.OKTA_API_TOKEN
관리 SDK용 Okta API 토큰입니다. Okta API에서 사용자 그룹을 가져오는 데 필요합니다.

getUserId?:

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

cache?:

PermissionCacheOptions
그룹 조회용 LRU 캐시를 구성합니다.
PermissionCacheOptions

maxSize?:

number
캐시할 수 있는 최대 사용자 수입니다.

ttlMs?:

number
밀리초 단위의 유효 기간입니다.
On this page