Google

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

Studio 사용자가 Google로 로그인할 때 이 기능을 사용하세요. 액세스는 하나 이상의 Google Workspace 도메인으로 제한되어야 합니다.

전제조건
전제조건에 대한 직접 링크

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

Google Cloud 프로젝트 만들기 또는 선택
웹 애플리케이션용 OAuth 클라이언트 설정
승인된 리디렉션 URI에 Mastra SSO 콜백 URL을 추가하세요.
RBAC를 사용하려는 경우 Google Workspace 그룹을 구성하세요.

Google 그룹스 RBAC의 경우 도메인 전체 위임으로 Google Workspace 서비스 계정을 구성하고 여기에 Directory API 읽기 전용 그룹 범위를 부여합니다.

https://www.googleapis.com/auth/admin.directory.group.readonly

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

.env
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://localhost:4111/api/auth/sso/callback
GOOGLE_COOKIE_PASSWORD=a-random-string-at-least-32-characters-long
GOOGLE_ALLOWED_DOMAINS=example.com

GOOGLE_SERVICE_ACCOUNT_EMAIL=service-account@project.iam.gserviceaccount.com
GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
GOOGLE_WORKSPACE_ADMIN_EMAIL=admin@example.com

노트

GOOGLE_COOKIE_PASSWORD세션 쿠키를 암호화합니다. 생략하면 서버를 다시 시작해도 유지되지 않는 자동 생성 값이 사용됩니다. 프로덕션을 위해 명시적으로 설정합니다.

MastraAuthGoogle은 GOOGLE_* 인증 변수를 자동으로 읽습니다. 위에 표시된 서비스 계정 변수는 MastraRBACGoogle에 전달하는 구성 코드에서 읽습니다.

설치
설치에 대한 직접 링크

MastraAuthGoogle 클래스를 사용하기 전에 @mastra/auth-google 패키지를 설치하세요.

npm
pnpm
Yarn
Bun

npm install @mastra/auth-google

pnpm add @mastra/auth-google

yarn add @mastra/auth-google

bun add @mastra/auth-google

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

환경 변수를 사용한 기본 사용법
환경 변수를 사용한 기본 사용법에 대한 직접 링크

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

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { MastraAuthGoogle } from '@mastra/auth-google'

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

경고

Workspace 액세스를 적용하려면 allowedDomains 또는 GOOGLE_ALLOWED_DOMAINS를 사용하세요. Mastra는 이메일 주소 접미사가 아니라 Google에서 검증한 hd 클레임을 검사합니다.

맞춤 구성
맞춤 구성에 대한 직접 링크

환경 변수에 의존하지 않으려면 생성자 옵션을 직접 전달하세요.

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'],
    }),
  },
})

Google 그룹스 RBAC로 인증
Google 그룹스 RBAC로 인증에 대한 직접 링크

Google Workspace 그룹을 Mastra 권한에 매핑하려면 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: [], // users with unmapped groups get no permissions
      },
    }),
  },
})

공급자 간 사용
공급자 간 사용에 대한 직접 링크

로그인에는 다른 인증 Provider(Auth0, Clerk 등)를 사용하고 RBAC에는 Google Workspace 그룹을 사용하세요. 다른 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 => {
        if (!user || typeof user !== 'object') return undefined

        const { email } = user as { email?: unknown }
        return typeof email === 'string' ? email : undefined
      },
      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: [],
      },
    }),
  },
})

사용 가능한 모든 구성 옵션은 MastraAuthGoogle을 참조하세요.

역할 매핑
역할 매핑에 대한 직접 링크

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

const rbac = new MastraRBACGoogle({
  roleMapping: {
    // full access to everything
    'admins@example.com': ['*'],

    // full access to agents and workflows
    'engineering@example.com': ['agents:*', 'workflows:*'],

    // read-only access
    'viewers@example.com': ['agents:read', 'workflows:read'],

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

그룹 이메일 주소는 기본적으로 역할 ID로 사용됩니다. 그룹 이름이나 다른 속성을 기준으로 매핑하려면 mapGroupToRoles를 사용하세요. _default 키는 다른 어떤 키와도 일치하지 않는 Google Workspace 그룹에 속한 사용자에게 권한을 할당합니다.

클라이언트 측 설정
클라이언트 측 설정에 대한 직접 링크

인증이 활성화되면 Mastra 경로에 대한 요청에 인증이 필요합니다. GOOGLE_CLIENT_SECRET으로 SSO를 활성화하면 MastraAuthGoogle은 Google 로그인을 사용하고 로그인 후 암호화된 세션 쿠키를 설정합니다.

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

src/mastra/index.ts
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthGoogle(),
    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',
})

무기명 토큰
무기명 토큰에 대한 직접 링크

Google ID 토큰을 Bearer 토큰으로 전달할 수도 있습니다. Mastra는 Google의 JWKS(JSON 웹 키 세트) 엔드포인트에 대해 토큰을 확인합니다.

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

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

더 많은 구성 옵션은 Mastra Client SDK를 참조하세요.

인증된 요청 만들기
인증된 요청 만들기에 대한 직접 링크

MastraClient
cURL

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 -X POST http://localhost:4111/api/agents/weatherAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-google-id-token>" \
  -d '{
    "messages": "Weather in London"
  }'

문제 해결
문제 해결에 대한 직접 링크

로그인 후 401 발생: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI가 Google Cloud OAuth 클라이언트와 일치하는지 확인하세요.
Workspace 사용자가 거부됨: GOOGLE_ALLOWED_DOMAINS가 Google ID 토큰의 hd 클레임과 일치하는지 확인하세요.
일반 Gmail 계정이 거부됨: Gmail 계정에는 Workspace hd 클레임이 없으므로 allowedDomains가 구성된 경우 예상되는 동작입니다.
RBAC가 기본 권한을 반환함: 사용자에 대해 확인된 역할이 없습니다. 사용자 이메일 또는 사용자 지정 getUserKey, Google 그룹 멤버십, roleMapping을 확인하세요. Directory API 조회가 실패하면 Provider는 _default를 반환하는 대신 오류를 발생시킵니다.
교차 출처로 쿠키가 전송되지 않음: MastraClient에서 credentials: "include"를 설정하고, 프런트엔드 출처 및 credentials: true로 server.cors를 구성하세요.
다시 시작하면 세션이 손실됨: GOOGLE_COOKIE_PASSWORD를 32자 이상의 안정적인 값으로 설정하세요. 설정하지 않으면 개발 환경에서 자동 생성된 키가 사용되며 다시 시작할 때마다 변경됩니다.

전제조건전제조건에 대한 직접 링크

설치설치에 대한 직접 링크

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

환경 변수를 사용한 기본 사용법환경 변수를 사용한 기본 사용법에 대한 직접 링크

맞춤 구성맞춤 구성에 대한 직접 링크

Google 그룹스 RBAC로 인증Google 그룹스 RBAC로 인증에 대한 직접 링크

공급자 간 사용공급자 간 사용에 대한 직접 링크

역할 매핑역할 매핑에 대한 직접 링크

클라이언트 측 설정클라이언트 측 설정에 대한 직접 링크

쿠키 세션(권장)쿠키 세션(권장)에 대한 직접 링크

무기명 토큰무기명 토큰에 대한 직접 링크

인증된 요청 만들기인증된 요청 만들기에 대한 직접 링크

문제 해결문제 해결에 대한 직접 링크

관련된관련된에 대한 직접 링크