[ADP-47] API 認證和授權

指導原則

使用者名稱、密碼、會話令牌、API 金鑰和敏感資訊絕不能(MUST NOT)出現在 URL 中。
每個 API 端點都應該(MUST)使用 OAuth2.0 或基於 JWT 的認證進行安全保護，根據您的使用場景選擇適合的認證方法：
- 使用 OAuth2.0 的情況：
  - 處理第三方應用程式的認證
  - 實現委託授權，讓用戶可以授權第三方應用程式訪問其資源
  - 支援多種認證流程，例如授權碼流程、隱式流程和客戶端流程
  - 更多關於 OAuth2.0 的規範和實踐請參閱 ADP-54
- 使用 JWT 的情況：
  - 為您自己的系統構建無狀態認證，無需在服務器端存儲會話信息
  - 需要在令牌中包含聲明或用戶資訊，以便在驗證過程中使用
- OAuth2.0 授權類型的詳細信息請參閱 ADP-54。
可(MAY)考慮使用 Api-Key 認證，參閱 ADP-55。
不應(SHOULD NOT)使用基本認證，
- 基本認證的安全性較低，因為它以易於解碼的格式傳輸用戶憑證，避免使用它來保護 API 端點，
- 不要這樣做：
```
```http
  GET /protected/resource HTTP/1.1
  Host: api.example.com
  Authorization: Basic <base64_encoded_credentials>
```
```
所有外部 API 必須(MUST)建立在 HTTPS 之上，
- 所有外部 API 通信必須(MUST)使用 HTTPS 加密，以保護傳輸中的數據免受竊聽和中間人攻擊，確保正確配置和維護 SSL/TLS 證書，
- 例外情況：安全內部網絡中的內部 API 可以(MAY)在滿足以下條件時不使用 HTTPS 運行：
  - 網絡完全與外部訪問隔離
  - 所有內部流量都受到監控和保護
  - 內部威脅的風險被認為是可接受的
- 注意：即使對於內部 API，在可能的情況下仍建議使用 HTTPS，以保持一致性和額外的安全性，
- 示例：（所有外部 API 的 URL 應以 https:// 開頭）
  http
```
GET /protected/resource HTTP/1.1
Host: api.example.com
```

應(SHOULD)實施基於角色的授權控制（RBAC），

實施 RBAC 以有效管理用戶權限，根據最小權限原則定義角色並分配權限，
RBAC 實施的最佳實踐：
- 為特定操作和資源定義細粒度權限
- 創建將相關權限分組的角色
- 將用戶分配給角色，而不是直接分配權限
- 定期審查和審核角色分配
- 如果複雜系統需要，實施分層角色結構

示例：

定義細粒度權限：

json

{
  "permissions": [
    "user:read",
    "user:create",
    "user:update",
    "user:delete",
    "report:view",
    "report:generate"
  ]
}

創建具有特定權限的角色：

json

{
  "roles": [
    {
      "name": "admin",
      "permissions": ["user:read", "user:create", "user:update", "user:delete", "report:view", "report:generate"]
    },
    {
      "name": "manager",
      "permissions": ["user:read", "report:view", "report:generate"]
    },
    {
      "name": "user",
      "permissions": ["user:read", "report:view"]
    }
  ]
}

將角色分配給用戶：

json

{
  "users": [
    {
      "username": "alice",
      "roles": ["admin"]
    },
    {
      "username": "bob",
      "roles": ["manager"]
    },
    {
      "username": "charlie",
      "roles": ["user"]
    }
  ]
}

在RBAC無法滿足特定資源和特定使用者之間的需求時，可能(MAY)需要使用ABAC。

Reference

ADIDAS API: Security

Changelog

2024.11.04: Add security concern
2025.01.08: Make API-Key be standalone document

[ADP-47] API 認證和授權 ​

指導原則 ​

Reference ​

Changelog ​

[ADP-47] API 認證和授權

指導原則

Reference

Changelog