持有者身份验证

持有者身份验证（也称为令牌身份验证）是一种 HTTP 身份验证方案，它涉及称为持有者令牌的安全令牌。“持有者身份验证”这个名称可以理解为“允许持有此令牌的人访问”。持有者令牌是一个神秘的字符串，通常由服务器响应登录请求而生成。客户端在向受保护的资源发出请求时，必须在 Authorization 标头中发送此令牌。

1
Authorization: Bearer <token>

持有者身份验证方案最初是在 OAuth 2.0 中作为 RFC 6750 的一部分创建的，但有时也单独使用。与基本身份验证类似，持有者身份验证应仅通过 HTTPS (SSL) 使用。

描述持有者身份验证

在 OpenAPI 3.0 中，持有者身份验证是一种安全方案，具有 type: http 和 scheme: bearer。您首先需要在 components/securitySchemes 下定义安全方案，然后使用 security 关键字将此方案应用于所需的范围 - 全局（如下例所示）或特定操作。

1
openapi: 3.0.0
2
---
3
# 1) Define the security scheme type (HTTP bearer)
4
components:
5
  securitySchemes:
6
    bearerAuth: # arbitrary name for the security scheme
7
      type: http
8
      scheme: bearer
9
      bearerFormat: JWT # optional, arbitrary value for documentation purposes
10

11
# 2) Apply the security globally to all operations
12
security:
13
  - bearerAuth: [] # use the same name as above

可选的 bearerFormat 是一个任意字符串，用于指定持有者令牌的格式。由于持有者令牌通常由服务器生成，因此 bearerFormat 主要用于文档目的，作为对客户端的提示。在上面的示例中，它是 “JWT”，表示 JSON Web Token。bearerAuth: [] 中的方括号 [] 包含 API 调用所需的安全范围列表。该列表为空，因为范围仅与 OAuth 2 和 OpenID Connect 一起使用。在上面的示例中，持有者身份验证全局应用于整个 API。如果只需要将其应用于几个操作，请在操作级别添加 security，而不是全局执行此操作。

1
paths:
2
  /something:
3
    get:
4
      security:
5
        - bearerAuth: []

持有者身份验证也可以与其他身份验证方法结合使用，如使用多种身份验证类型中所述。

401 响应

您还可以定义针对不包含正确的持有者令牌的请求返回的 401“未授权”响应。由于 401 响应将由多个操作使用，因此您可以在全局 components/responses 部分中定义它，并通过 $ref 在其他地方引用。

1
paths:
2
  /something:
3
    get:
4
      ...
5
      responses:
6
        '401':
7
          $ref: '#/components/responses/UnauthorizedError'
8
        ...
9
    post:
10
      ...
11
      responses:
12
        '401':
13
          $ref: '#/components/responses/UnauthorizedError'
14
        ...
15

16
components:
17
  responses:
18
    UnauthorizedError:
19
      description: Access token is missing or invalid

要了解有关 responses 的更多信息，请参阅描述响应。

没有找到您要找的内容？询问社区
发现错误？请告知我们