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

# MastraAuthFirebase 類別

`MastraAuthFirebase` 類別使用 Firebase Authentication 為 Mastra 提供身份驗證。它使用 Firebase ID token 驗證傳入的請求，並透過 `auth` 選項與 Mastra 伺服器整合。

## 使用範例

### 使用環境變數的基本用法

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
export const mastra = new Mastra({
  server: {
    auth: new MastraAuthFirebase(),
  },
})
```

### 自訂設定

```typescript
import { Mastra } from '@mastra/core'
import { MastraAuthFirebase } from '@mastra/auth-firebase'

export const mastra = new Mastra({
  server: {
    auth: new MastraAuthFirebase({
      serviceAccount: '/path/to/service-account-key.json',
      databaseId: 'your-database-id',
    }),
  },
})
```

## 建構函數參數

**serviceAccount** (`string`): Firebase 服務帳戶 JSON 文件的路徑。此文件包含在伺服器端驗證 Firebase ID token 所需的憑證。 (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)

**databaseId** (`string`): 要使用的 Firestore 資料庫 ID。預設資料庫通常為 '(default)'。 (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)

**name** (`string`): 身份驗證 Provider 實例的自訂名稱。 (Default: `"firebase"`)

**authorizeUser** (`(user: FirebaseUser) => Promise<boolean> | boolean`): 自訂授權函數，用於判斷是否應授予用戶存取權。此函數會在 token 驗證後呼叫。預設會檢查以用戶 UID 為鍵的 'user\_access' collection 中是否存在文件。

## 環境變數

未提供建構函數選項時，系統會自動使用以下環境變數：

**FIREBASE\_SERVICE\_ACCOUNT** (`string`): Firebase 服務帳戶 JSON 文件的路徑。未提供 serviceAccount 選項時使用。

**FIRESTORE\_DATABASE\_ID** (`string`): Firestore 資料庫 ID。資料庫設定的主要環境變數。

**FIREBASE\_DATABASE\_ID** (`string`): Firestore 資料庫 ID 的替代環境變數。未設定 FIRESTORE\_DATABASE\_ID 時使用。

## 預設授權行為

預設情況下，`MastraAuthFirebase` 使用 Firestore 管理用戶存取權：

1. 成功驗證 Firebase ID token 後，會呼叫 `authorizeUser` 方法
2. 它會檢查 `user_access` collection 中是否存在以用戶 UID 作為文件 ID 的文件
3. 如果文件存在，用戶便獲得授權；否則會拒絕存取
4. 所使用的 Firestore 資料庫由 `databaseId` 參數或環境變數決定

## Firebase 用戶類型

`authorizeUser` 函數所使用的 `FirebaseUser` 類型對應 Firebase 的 `DecodedIdToken` interface，其中包括：

- `uid`：用戶的唯一識別碼
- `email`：用戶的電郵地址（如有）
- `email_verified`：電郵是否已驗證
- `name`：用戶的顯示名稱（如有）
- `picture`：用戶個人資料圖片的 URL（如有）
- `auth_time`：用戶通過身份驗證的時間
- 以及其他標準 JWT claim

## 相關內容

[MastraAuthFirebase 類別](https://mastra.zisheng.pro/zh-HK/docs/server/auth/firebase)