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

# MastraAuthGoogle クラスと MastraRBACGoogle クラス

## MastraAuthGoogle クラス

`MastraAuthGoogle` クラスは、Google Workspace を使用した認証を Mastra に提供します。暗号化されたセッション Cookie を使用する 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`): Google に hd として渡すホストドメインのログインヒント。これはヒントにすぎず、認可には使用されません。 (Default: `process.env.GOOGLE_HOSTED_DOMAIN or the single allowed domain`)

**session** (`GoogleSessionOptions`): セッション Cookie の設定。

**session.cookieName** (`string`): セッション Cookie の名前。

**session.cookieMaxAge** (`number`): Cookie の最大有効期間（秒）。

**session.cookiePassword** (`string`): セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。設定しない場合、開発環境では自動生成された値が使用されますが、再起動後は保持されません。

**session.secureCookies** (`boolean`): セッション Cookie に 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`): セッション Cookie を暗号化するためのパスワード。32 文字以上である必要があります。

**GOOGLE\_ALLOWED\_DOMAINS** (`string`): 許可する Google Workspace ホストドメインのカンマ区切りリスト。

**GOOGLE\_HOSTED\_DOMAIN** (`string`): SSO ログイン時に Google に渡すホストドメインのログインヒント。

### 認証フロー

`MastraAuthGoogle` は、次の順序でリクエストを認証します。

1. **セッション Cookie。** SSO が有効な場合、Provider は暗号化されたセッション Cookie を読み取り、復号します。有効期限内の有効なセッションによってユーザーが認証されます。
2. **Google ID トークンへのフォールバック**：有効なセッション Cookie がない場合、`Authorization` ヘッダーのトークンを Google の JWKS エンドポイントに対して検証します。

認証後、`authorizeUser` はユーザーに有効な Google ユーザー ID があること、トークンから取得した有効期限を過ぎていないこと、およびドメインが設定されている場合はユーザーの検証済み `hd` クレームが `allowedDomains` と一致することを確認します。

### 認証メソッド

#### `authenticateToken(token, request?)`

Google ID トークンを認証します。SSO が有効な場合、このメソッドは Bearer トークンを検証する前に、暗号化されたセッション Cookie を確認します。

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

戻り値：`Promise<GoogleUser | null>`

#### `getCurrentUser(request)`

セッション Cookie または 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 とともに `MastraRBACGoogle` を使用するには、`rbac` オプションに渡します。

```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 グループと `roleMapping` から解決された Mastra の権限を返します。

```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)`

ユーザーが要求された権限を少なくとも1つ持っているかどうかを確認します。

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

戻り値：`Promise<boolean>`

#### `getAvailableRoles()`

`roleMapping` に設定されたロール ID を、`_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)`

メールアドレスなど、1つの 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/ja/docs/server/auth/google)