跳到内容

不记名身份验证

不记名身份验证（也称为令牌身份验证）是一种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.4
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 的更多信息，请参阅描述响应。

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

© . All rights reserved.