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

# MastraAuthGoogle 및 MastraRBACGoogle 클래스

## MastraAuthGoogle 클래스

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

### 사용예

```typescript
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`): Google OAuth 클라이언트 ID입니다. (Default: `process.env.GOOGLE_CLIENT_ID`)

**clientSecret** (`string`): Google OAuth 클라이언트 비밀 값입니다. Studio SSO에 필요합니다. (Default: `process.env.GOOGLE_CLIENT_SECRET`)

**redirectUri** (`string`): SSO 콜백의 OAuth 리디렉션 URI입니다. Google Cloud OAuth 클라이언트에 구성된 리디렉션 URI와 일치해야 합니다. (Default: `process.env.GOOGLE_REDIRECT_URI`)

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

**allowedDomains** (`string | string[]`): 허용된 Google Workspace 호스팅 도메인입니다. Mastra는 검증된 hd 클레임을 기준으로 이를 검증합니다. (Default: `process.env.GOOGLE_ALLOWED_DOMAINS`)

**hostedDomain** (`string`): hd로 Google에 전달되는 호스팅 도메인 로그인 힌트입니다. 힌트일 뿐이며 권한 부여에는 사용되지 않습니다. (Default: `process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain`)

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

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

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

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

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

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

### 환경변수

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

**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 토큰을 확인하기 전에 암호화된 세션 쿠키를 확인합니다.

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

보고:`Promise<GoogleUser | null>`

#### `getCurrentUser(request)`

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

```typescript
const user = await auth.getCurrentUser(request)
```

보고:`Promise<GoogleUser | null>`

#### `authorizeUser(user)`

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

```typescript
const allowed = auth.authorizeUser(user)
```

보고:`boolean`

#### `getUser(userId)`

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

```typescript
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 라이선스가 필요합니다. 개발 중에는 라이선스 없이 작동하므로 로컬에서 사용해 볼 수 있지만 프로덕션에는 라이선스가 필요합니다. 자세한 내용은 [영업팀에 문의](https://mastra.ai/contact)하세요.

### 사용예

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

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

```typescript
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에 액세스하기 위한 서비스 계정 자격 증명입니다.

**serviceAccount.clientEmail** (`string`): Google 서비스 계정 이메일입니다.

**serviceAccount.privateKey** (`string`): PEM으로 인코딩된 비공개 키입니다. .env 파일에서 이스케이프된 \n 값을 지원합니다.

**serviceAccount.privateKeyId** (`string`): 선택적 비공개 키 ID입니다.

**serviceAccount.subject** (`string`): 도메인 전체 위임을 통해 가장할 Workspace 관리자 사용자입니다.

**serviceAccount.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 캐시를 구성합니다.

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

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

### RBAC 방법

#### `getRoles(user)`

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

```typescript
const roles = await rbac.getRoles(user)
```

보고:`Promise<string[]>`

#### `getPermissions(user)`

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

```typescript
const permissions = await rbac.getPermissions(user)
```

보고:`Promise<string[]>`

#### `hasPermission(user, permission)`

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

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

보고:`Promise<boolean>`

#### `hasRole(user, role)`

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

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

보고:`Promise<boolean>`

#### `hasAllPermissions(user, permissions)`

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

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

보고:`Promise<boolean>`

#### `hasAnyPermission(user, permissions)`

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

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

보고:`Promise<boolean>`

#### `getAvailableRoles()`

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

```typescript
const roles = await rbac.getAvailableRoles()
```

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

#### `getPermissionsForRole(roleId)`

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

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

보고:`Promise<string[]>`

#### `clearCache()`

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

```typescript
rbac.clearCache()
```

보고:`void`

#### `clearUserCache(userKey)`

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

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

보고:`void`

#### `getCacheStats()`

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

```typescript
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 인증 문서](https://mastra.zisheng.pro/ko/docs/server/auth/google)