MastraAuthGoogle 및 MastraRBACGoogle 클래스

MastraAuthGoogle 클래스

MastraAuthGoogle 클래스는 Google Workspace를 사용하여 Mastra에 인증을 제공합니다. 암호화된 세션 쿠키를 사용하는 OAuth 2.0 / OIDC 로그인 흐름을 구현하고 Google ID 토큰을 검증하며, auth 옵션을 사용하여 Mastra 서버와 통합됩니다.

사용예

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle({
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      redirectUri: process.env.GOOGLE_REDIRECT_URI,
      allowedDomains: ['example.com'],
    }),
  },
})

노트

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

생성자 매개변수

clientId?:

string

= process.env.GOOGLE_CLIENT_ID

Google OAuth 클라이언트 ID입니다.

clientSecret?:

string

= process.env.GOOGLE_CLIENT_SECRET

Google OAuth 클라이언트 비밀 값입니다. Studio SSO에 필요합니다.

redirectUri?:

string

= process.env.GOOGLE_REDIRECT_URI

SSO 콜백의 OAuth 리디렉션 URI입니다. Google Cloud OAuth 클라이언트에 구성된 리디렉션 URI와 일치해야 합니다.

scopes?:

string[]

= ['openid', 'profile', 'email']

로그인 흐름 중 요청되는 OAuth 범위입니다.

allowedDomains?:

string | string[]

= process.env.GOOGLE_ALLOWED_DOMAINS

허용된 Google Workspace 호스팅 도메인입니다. Mastra는 검증된 hd 클레임을 기준으로 이를 검증합니다.

hostedDomain?:

string

= process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain

hd로 Google에 전달되는 호스팅 도메인 로그인 힌트입니다. 힌트일 뿐이며 권한 부여에는 사용되지 않습니다.

session?:

GoogleSessionOptions

세션 쿠키 구성입니다.

GoogleSessionOptions

cookieName?:

string

세션 쿠키의 이름입니다.

cookieMaxAge?:

number

쿠키의 최대 수명(초)입니다.

cookiePassword?:

string

세션 쿠키를 암호화하기 위한 비밀번호입니다. 32자 이상이어야 합니다. 설정하지 않으면 개발 환경에서 자동 생성된 값을 사용하며, 이 값은 재시작 후 유지되지 않습니다.

secureCookies?:

boolean

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

name?:

string

= 'google'

인증 Provider 인스턴스의 사용자 정의 이름입니다.

환경변수

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

GOOGLE_CLIENT_ID:

string

Google Cloud OAuth 클라이언트의 Google OAuth 클라이언트 ID입니다.

GOOGLE_CLIENT_SECRET?:

string

Google OAuth 클라이언트 비밀 값입니다. SSO 권한 부여 코드 흐름에 필요합니다.

GOOGLE_REDIRECT_URI?:

string

SSO 콜백의 OAuth 리디렉션 URI입니다.

GOOGLE_COOKIE_PASSWORD?:

string

세션 쿠키를 암호화하기 위한 비밀번호입니다. 32자 이상이어야 합니다.

GOOGLE_ALLOWED_DOMAINS?:

string

허용할 Google Workspace 호스팅 도메인을 쉼표로 구분한 목록입니다.

GOOGLE_HOSTED_DOMAIN?:

string

SSO 로그인 중 Google에 전달되는 호스팅 도메인 로그인 힌트입니다.

인증 흐름

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

1. 세션 쿠키.SSO가 활성화되면 공급자는 암호화된 세션 쿠키를 읽고 해독합니다. 만료되지 않은 유효한 세션이 사용자를 인증합니다.
2. Google ID 토큰 대체: 유효한 세션 쿠키가 없으면Authorization header token against Google's JWKS endpoint.

인증 후 authorizeUser는 사용자에게 유효한 Google 사용자 ID가 있는지, 토큰에서 파생된 만료 시간이 지나지 않았는지, 도메인이 구성된 경우 사용자의 검증된 hd 클레임이 allowedDomains와 일치하는지 확인합니다.

인증 방법

authenticateToken(token, request?)

Google ID 토큰을 인증합니다. SSO가 활성화되면 이 방법은 Bearer 토큰을 확인하기 전에 암호화된 세션 쿠키를 확인합니다.

const user = await auth.authenticateToken(idToken, request)

보고:Promise<GoogleUser | null>

getCurrentUser(request)

세션 쿠키 또는 Bearer Google ID 토큰에서 인증된 사용자를 반환합니다.

const user = await auth.getCurrentUser(request)

보고:Promise<GoogleUser | null>

authorizeUser(user)

사용자에게 ID가 있고 만료되지 않았으며, 도메인이 구성된 경우 allowedDomains와 일치하면 true를 반환합니다.

const allowed = auth.authorizeUser(user)

보고:boolean

getUser(userId)

null을 반환합니다. Google ID 토큰은 직접 검증되므로 이 Provider는 ID를 사용한 사용자 조회를 수행하지 않습니다.

const user = await auth.getUser(userId)

보고:Promise<GoogleUser | null>

GoogleUser유형

GoogleUser 타입은 기본 EEUser 인터페이스를 Google별 필드로 확장합니다.

id:

string

Mastra 사용자 ID입니다. Google sub 클레임을 사용합니다.

googleId:

string

Google 계정 주체 식별자입니다.

email?:

string

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

name?:

string

Google 프로필 클레임의 사용자 표시 이름입니다.

avatarUrl?:

string

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

hostedDomain?:

string

검증된 hd 클레임의 Google Workspace 호스팅 도메인입니다.

expiresAt?:

Date

사용 가능한 경우 검증된 ID 토큰의 만료 시간입니다.

emailVerified?:

boolean

Google에서 이메일 주소가 검증되었다고 보고하는지 여부입니다.

groups?:

string[]

선택적으로 미리 확인된 Google Workspace 그룹 역할 ID입니다.

MastraRBACGoogle 클래스

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

노트

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

사용예

인증 Provider의 rbac 옵션에 MastraRBACGoogle을 전달하여 함께 사용하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthGoogle, MastraRBACGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle(),
    rbac: new MastraRBACGoogle({
      serviceAccount: {
        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
      },
      roleMapping: {
        'admins@example.com': ['*'],
        'engineering@example.com': ['agents:*', 'workflows:*', 'tools:*'],
        'viewers@example.com': ['agents:read', 'workflows:read'],
        _default: [],
      },
    }),
  },
})

다른 인증 Provider와 함께 Google Workspace RBAC를 사용하려면 다른 Provider의 사용자 객체에서 Google Directory API 사용자 키를 확인하는 getUserKey 함수를 전달하세요.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraAuthAuth0 } from '@mastra/auth-auth0'
import { MastraRBACGoogle } from '@mastra/auth-google'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthAuth0(),
    rbac: new MastraRBACGoogle({
      getUserKey: user => user.email,
      serviceAccount: {
        clientEmail: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL!,
        privateKey: process.env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY!,
        subject: process.env.GOOGLE_WORKSPACE_ADMIN_EMAIL!,
      },
      roleMapping: {
        'engineering@example.com': ['agents:*', 'workflows:*'],
        'admins@example.com': ['*'],
        _default: [],
      },
    }),
  },
})

생성자 매개변수

roleMapping:

RoleMapping

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

accessToken?:

string

미리 발급받은 Workspace Directory API 액세스 토큰입니다.

getAccessToken?:

() => Promise<string> | string

Workspace Directory API 액세스 토큰을 반환하는 콜백입니다.

serviceAccount?:

GoogleWorkspaceServiceAccount

도메인 전체 위임을 통해 Directory API에 액세스하기 위한 서비스 계정 자격 증명입니다.

GoogleWorkspaceServiceAccount

clientEmail:

string

Google 서비스 계정 이메일입니다.

privateKey:

string

PEM으로 인코딩된 비공개 키입니다. .env 파일에서 이스케이프된 \n 값을 지원합니다.

privateKeyId?:

string

선택적 비공개 키 ID입니다.

subject?:

string

도메인 전체 위임을 통해 가장할 Workspace 관리자 사용자입니다.

scopes?:

string[]

서비스 계정 토큰의 OAuth 범위입니다.

getUserKey?:

(user: unknown) => string | undefined

인증된 사용자에서 Directory API userKey를 추출합니다. 기본값은 user.email입니다.

mapGroupToRoles?:

(group: GoogleWorkspaceGroup) => string[]

Google Workspace 그룹을 역할 ID에 매핑합니다. 기본값은 [group.email]입니다.

cache?:

PermissionCacheOptions

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

PermissionCacheOptions

maxSize?:

number

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

ttlMs?:

number

밀리초 단위의 유효 기간입니다.

RBAC 방법

getRoles(user)

사용자의 Google Workspace 그룹 역할 ID를 반환합니다.

const roles = await rbac.getRoles(user)

보고:Promise<string[]>

getPermissions(user)

Google Workspace 그룹에서 확인된 Mastra 권한을 반환하고roleMapping.

const permissions = await rbac.getPermissions(user)

보고:Promise<string[]>

hasPermission(user, permission)

사용자에게 권한이 있는지 확인합니다.

const canReadAgents = await rbac.hasPermission(user, 'agents:read')

보고:Promise<boolean>

hasRole(user, role)

사용자가 특정 Google Workspace 그룹 역할을 결정했는지 확인합니다.

const isAdmin = await rbac.hasRole(user, 'admins@example.com')

보고:Promise<boolean>

hasAllPermissions(user, permissions)

사용자가 요청한 모든 권한을 가지고 있는지 확인합니다.

const canManageAgents = await rbac.hasAllPermissions(user, ['agents:read', 'agents:update'])

보고:Promise<boolean>

hasAnyPermission(user, permissions)

사용자에게 요청된 권한이 하나 이상 있는지 확인합니다.

const canReadSomething = await rbac.hasAnyPermission(user, ['agents:read', 'workflows:read'])

보고:Promise<boolean>

getAvailableRoles()

구성된 역할 ID를 반환합니다.roleMapping, excluding _default.

const roles = await rbac.getAvailableRoles()

보고:Promise<{ id: string; name: string }[]>

getPermissionsForRole(roleId)

역할 ID에 대해 구성된 권한을 반환합니다.

const permissions = await rbac.getPermissionsForRole('engineering@example.com')

보고:Promise<string[]>

clearCache()

캐시된 Google Workspace 그룹 조회를 모두 지웁니다.

rbac.clearCache()

보고:void

clearUserCache(userKey)

이메일 주소와 같은 하나의 Directory API 사용자 키에 대한 캐시된 그룹 조회를 지웁니다.

rbac.clearUserCache('user@example.com')

보고:void

getCacheStats()

현재 그룹 조회 캐시 크기와 최대 크기를 반환합니다.

const stats = rbac.getCacheStats()

보고:{ size: number; maxSize: number }

추가 구성

MastraRBACGoogle은 GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=...를 사용하며 페이지네이션을 처리합니다. 프로덕션 Google Workspace 배포에서는 도메인 전체 위임이 설정된 서비스 계정을 제공하세요. 애플리케이션에서 이미 Google API 토큰을 관리한다면 accessToken / getAccessToken을 전달하세요. user.groups가 이미 배열이면 MastraRBACGoogle은 해당 값을 사용하고 Directory API를 호출하지 않습니다. 빈 groups 배열은 사용자에게 Google 그룹 역할이 없다는 의미이며, _default가 구성되어 있으면 _default 권한으로 확인됩니다. MastraRBACGoogle은 서비스 계정 환경 변수를 자동으로 읽지 않습니다. serviceAccount 옵션을 통해 서비스 계정 자격 증명을 전달하거나 accessToken / getAccessToken을 전달하세요.

관련된

Google 인증 문서