[ADP-123] Authorization

授權標頭允許 API 識別發出請求的用戶或系統，並確定他們是否有權限訪問所請求的資源。

概述

Authorization 標頭用於提供憑證，以便用戶代理與伺服器進行身份驗證。可以使用各種身份驗證方案，如 Basic、Bearer 和自定義方案。在現代 API 中，最常見的方法是 Bearer 令牌，通常與 OAuth 2.0 結合使用。

常見的身份驗證方案

基本身份驗證:
- 憑證使用 Base64 編碼。
- 除非與 HTTPS 一起使用，否則不建議在生產環境中使用，因為存在安全隱患。
示例:
http
```
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
```
Bearer 令牌:
- 由授權伺服器發行的令牌，通常與 OAuth 2.0 一起使用。
- 此令牌包含在每個對受保護資源的請求的 Authorization 標頭中。
示例:
http
```
Authorization: Bearer <token>
```
自定義方案:
- 根據特定的安全要求，可以定義自定義方案。參閱 ADP-363。
示例:
http
```
Authorization: CustomScheme <credentials>
```

指導

應該(SHOULD)優先使用 bearer 方案。
- 如果計劃使用自定義方案，請詳細記錄。
必須(MUST)使用 HTTPS 以確保通過 Authorization 標頭傳輸的憑證的安全性。
應該(SHOULD)實施令牌過期和更新機制以增強安全性。建議使用短期令牌和刷新令牌。
可以(MAY)定義和執行範圍和權限以控制對 API 各個部分的訪問。
應該(SHOULD)為身份驗證和授權失敗提供清晰的錯誤消息，使用標準 HTTP 狀態碼，如 401(未授權)和 403(禁止)。

OpenAPI 規範示例

以下是一個在 OpenAPI 文件中指定 Authorization 標頭的示例，使用 Bearer 令牌身份驗證方案，並結合 HTTP Problem (RFC 9457) 進行錯誤處理。

yaml

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: An example API demonstrating the use of the Authorization header with HTTP Problem (RFC 9457) for error handling.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: A URI reference identifying the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri
          description: A URI reference identifying the specific occurrence of the problem.
security:
  - BearerAuth: []
paths:
  /users:
    get:
      summary: Retrieve a list of users
      security:
        - BearerAuth: []
      responses:
        '200':
          description: A JSON array of user objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      example: 1
                    name:
                      type: string
                      example: John Doe
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /users/{id}:
    get:
      summary: Retrieve a user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: The ID of the user to retrieve
          schema:
            type: integer
      security:
        - BearerAuth: []
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 1
                  name:
                    type: string
                    example: John Doe
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'

TIP

💡 Security 安全性可以全局應用或部分應用於特定操作。

TIP

💡 安全性可以全局應用或部分應用於特定操作。

[ADP-123] Authorization ​

概述 ​

常見的身份驗證方案 ​

指導 ​

OpenAPI 規範示例 ​

參考 ​

[ADP-123] Authorization

概述

常見的身份驗證方案

指導

OpenAPI 規範示例

參考