> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 驗證後呼叫。預設會檢查 'user\_access' collection 中是否存在以使用者 UID 為 key 的 document。

## 環境變數

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

**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` method
2. 它會檢查 `user_access` collection 中是否存在以使用者 UID 為 document ID 的 document
3. 如果 document 存在，使用者即獲授權；否則會拒絕存取
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-TW/docs/server/auth/firebase)