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

# Simple Auth

`SimpleAuth` 類別使用基本的權杖至用戶映射提供權杖式身份驗證。它包含在 `@mastra/core/server` 中，適用於開發、測試及基本 API 金鑰身份驗證情境。

## 使用情境

- 本機開發及測試
- 簡單的 API 金鑰身份驗證
- 整合完整的身份 Provider 前製作原型
- 使用靜態權杖的內部服務

## 安裝

`SimpleAuth` 已包含在 `@mastra/core` 中，不需要額外的依賴套件。

```typescript
import { SimpleAuth } from '@mastra/core/server'
```

## 使用範例

```typescript
import { Mastra } from '@mastra/core'
import { SimpleAuth } from '@mastra/core/server'

// Define your user type
type User = {
  id: string
  name: string
  role: 'admin' | 'user'
}

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth<User>({
      tokens: {
        'sk-admin-token-123': {
          id: 'user-1',
          name: 'Admin User',
          role: 'admin',
        },
        'sk-user-token-456': {
          id: 'user-2',
          name: 'Regular User',
          role: 'user',
        },
      },
    }),
  },
})
```

## 配置選項

| 選項              | 類型                           | 必填 | 說明                  |
| --------------- | ---------------------------- | -- | ------------------- |
| `tokens`        | `Record<string, TUser>`      | 是  | 權杖至用戶物件的映射          |
| `headers`       | `string \| string[]`         | 否  | 要檢查權杖的額外標頭          |
| `name`          | `string`                     | 否  | 用於記錄日誌的 Provider 名稱 |
| `authorizeUser` | `(user, request) => boolean` | 否  | 自訂授權函式              |
| `protected`     | `(RegExp \| string)[]`       | 否  | 需要身份驗證的路徑           |
| `public`        | `(RegExp \| string)[]`       | 否  | 略過身份驗證的路徑           |

### 預設標頭

SimpleAuth 預設會檢查以下標頭：

- `Authorization`（可帶或不帶 `Bearer` 前綴）
- `X-Playground-Access`

使用 `headers` 選項加入自訂標頭：

```typescript
new SimpleAuth({
  tokens: {/* ... */},
  headers: ['X-API-Key', 'X-Custom-Auth'],
})
```

## 發出已通過身份驗證的請求

在 `Authorization` 標頭中加入權杖：

```bash
curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-admin-token-123" \
  -d '{"messages": "Hello"}'
```

或不使用 `Bearer` 前綴：

```bash
curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: sk-admin-token-123" \
  -d '{"messages": "Hello"}'
```

## 自訂授權

加入基於角色或自訂的授權邏輯：

```typescript
new SimpleAuth<User>({
  tokens: {
    'sk-admin-token': { id: '1', name: 'Admin', role: 'admin' },
    'sk-user-token': { id: '2', name: 'User', role: 'user' },
  },
  authorizeUser: (user, request) => {
    // Only admins can access /admin routes
    if (request.url.includes('/admin')) {
      return user.role === 'admin'
    }
    return true
  },
})
```

## 環境變數

如需模擬生產環境的設定，可從環境變數載入權杖：

```typescript
const tokens: Record<string, User> = {}

// Load from environment
const adminToken = process.env.ADMIN_API_KEY
if (adminToken) {
  tokens[adminToken] = { id: 'admin', name: 'Admin', role: 'admin' }
}

const userToken = process.env.USER_API_KEY
if (userToken) {
  tokens[userToken] = { id: 'user', name: 'User', role: 'user' }
}

export const mastra = new Mastra({
  server: {
    auth: new SimpleAuth({ tokens }),
  },
})
```

## 配合 `MastraClient` 使用

使用權杖配置客戶端：

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
  headers: {
    Authorization: 'Bearer sk-admin-token-123',
  },
})

const agent = client.getAgent('myAgent')
const response = await agent.generate('Hello')
```

## 限制

SimpleAuth 的設計以簡單易用為目標，而非保障生產環境安全：

- 權杖儲存在記憶體中
- 不支援權杖到期或更新
- 不進行密碼學驗證
- 所有權杖都必須在啟動時已知

對於生產環境應用程式，請考慮使用 [JWT](https://mastra.zisheng.pro/zh-HK/docs/server/auth/jwt)、[Clerk](https://mastra.zisheng.pro/zh-HK/docs/server/auth/clerk)、[Auth0](https://mastra.zisheng.pro/zh-HK/docs/server/auth/auth0) 或其他身份 Provider。