BLUEPRINT

第七章：安全與認證

7.1 概述

安全機制是協定的重要組成部分，確保技能提供者能夠控制誰可以發現和呼叫其技能。協定支援多種認證方式和存取控制策略，在開放性與安全性之間取得平衡。

7.2 存取控制策略

三級存取控制

級別發現可見性呼叫權限適用情境
public所有人可見無需認證即可呼叫開放 API、公共知識庫
restricted所有人可見需認證後呼叫商業 API、付費服務
private僅認證後可見需認證後呼叫內部工具、私有服務

存取控制與發現的關係

  • 未認證請求存取 Well-Known URI 時：
    • 回傳所有 public 和 restricted 技能
    • 不回傳 private 技能
  • 認證後請求存取 Well-Known URI 時：
    • 回傳所有技能（包括 private）

7.3 認證方式

API Key 認證

最簡單的認證方式，透過 HTTP Header 傳遞金鑰。

描述符宣告：

{
  "type": "api_key",
  "description": "透過 HTTP Header 傳遞 API Key",
  "header": "X-API-Key"
}

呼叫時附加 Header：

POST /invoke HTTP/1.1
Host: api.example.com
X-API-Key: sk-your-api-key-here
Content-Type: application/json

OAuth 2.0 認證

適用於需要細粒度權限控制的情境。

描述符宣告：

{
  "type": "oauth2",
  "oauth2": {
    "authorization_url": "https://example.com/oauth/authorize",
    "token_url": "https://example.com/oauth/token",
    "scopes": {
      "skill:invoke": "呼叫技能",
      "skill:read": "讀取技能資訊",
      "skill:admin": "管理技能設定"
    }
  }
}

呼叫時附加 Bearer Token：

POST /invoke HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

自訂認證

適用於非標準認證情境，提供者透過 instructions 欄位說明認證方式。

描述符宣告：

{
  "type": "custom",
  "custom": {
    "instructions": "使用 HMAC-SHA256 對請求主體簽章，將簽章放入 X-Signature header",
    "parameters": [
      {
        "name": "secret_key",
        "type": "string",
        "description": "用於 HMAC 簽章的金鑰",
        "required": true
      }
    ]
  }
}

無認證

公開技能無需認證：

{
  "type": "none"
}

7.4 認證錯誤處理

認證失敗（401）

未提供有效憑證時：

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required to invoke this skill",
    "details": {
      "required_auth_type": "oauth2",
      "authorization_url": "https://example.com/oauth/authorize"
    }
  }
}

權限不足（403）

憑證有效但無權存取：

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions to invoke this skill",
    "details": {
      "required_scopes": ["skill:invoke"],
      "current_scopes": ["skill:read"]
    }
  }
}

7.5 安全最佳實務

  1. 所有通訊應使用 HTTPS
  2. API Key 應透過 Header 傳遞，避免出現在 URL 中
  3. OAuth 2.0 Token 應設定合理的到期時間
  4. 技能提供者應實施速率限制以防止濫用
  5. 敏感技能應使用 private 存取策略，避免被未授權方發現