跳到内容

身份验证

OpenAPI 使用术语 安全方案 来表示身份验证和授权方案。OpenAPI 3.0 允许您描述使用以下安全方案保护的 API

请点击上面的链接，查看有关特定安全类型的指南，或继续阅读以了解如何描述一般的安全性。

与 OpenAPI 2.0 的更改

如果您之前使用过 OpenAPI 2.0，以下是帮助您开始使用 OpenAPI 3.0 的更改摘要

  • securityDefinitions 已重命名为 securitySchemes 并移至 components 内。
  • type: basic 已替换为 type: http 和 scheme: basic。
  • 新的 type: http 是所有 HTTP 安全方案（包括 Basic、Bearer 和其他）的总括类型，scheme 关键字表示方案类型。
  • API 密钥现在可以 in: cookie 发送。
  • 添加了对 OpenID Connect 发现的支持 (type: openIdConnect)。
  • OAuth 2 安全方案现在可以定义多个 flows。
  • OAuth 2 flows 已重命名为与 OAuth 2 规范 匹配：accessCode 现在为 authorizationCode，而 application 现在为 clientCredentials。

描述安全性

使用 securitySchemes 和 security 关键字描述安全性。您可以使用 securitySchemes 定义 API 支持的所有安全方案，然后使用 security 将特定方案应用于整个 API 或各个操作。

步骤 1. 定义 securitySchemes

API 使用的所有安全方案必须在全局 components/securitySchemes 部分中定义。此部分包含命名安全方案的列表，其中每个方案的 type 可以是

安全方案的其他必需属性取决于 type。以下示例显示了如何定义各种安全方案。BasicAuth、BearerAuth 名称和其他名称是任意名称，将用于从规范中的其他位置引用这些定义。

1
components:
2
  securitySchemes:
3
    BasicAuth:
4
      type: http
5
      scheme: basic
6


7
    BearerAuth:
8
      type: http
9
      scheme: bearer
10


11
    ApiKeyAuth:
12
      type: apiKey
13
      in: header
14
      name: X-API-Key
15


16
    OpenID:
17
      type: openIdConnect
18
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
19


20
    OAuth2:
21
      type: oauth2
22
      flows:
23
        authorizationCode:
24
          authorizationUrl: https://example.com/oauth/authorize
25
          tokenUrl: https://example.com/oauth/token
26
          scopes:
27
            read: Grants read access
28
            write: Grants write access
29
            admin: Grants access to admin operations

步骤 2. 应用安全性

在 securitySchemes 部分中定义安全方案后，可以通过在根级别或操作级别分别添加 security 部分，将它们应用于整个 API 或各个操作。当在根级别使用时，security 会将指定的安全方案全局应用于所有 API 操作，除非在操作级别被覆盖。在以下示例中，可以使用 API 密钥或 OAuth 2 对 API 调用进行身份验证。ApiKeyAuth 和 OAuth2 名称是指之前在 securitySchemes 中定义的方案。

1
security:
2
  - ApiKeyAuth: []
3
  - OAuth2:
4
      - read
5
      - write
6
# The syntax is:
7
# - scheme name:
8
#     - scope 1
9
#     - scope 2

对于每个方案，您需要指定 API 调用所需的安全作用域列表（请参阅下文）。作用域仅用于 OAuth 2 和 OpenID Connect 发现；其他安全方案使用空数组 [] 代替。全局 security 可以在各个操作中被覆盖，以使用不同的身份验证类型、不同的 OAuth/OpenID 作用域或根本不使用身份验证

1
paths:
2
  /billing_info:
3
    get:
4
      summary: Gets the account billing info
5
      security:
6
        - OAuth2: [admin] # Use OAuth with a different scope
7
      responses:
8
        "200":
9
          description: OK
10
        "401":
11
          description: Not authenticated
12
        "403":
13
          description: Access token does not have the required scope
14


15
  /ping:
16
    get:
17
      summary: Checks if the server is running
18
      security: [] # No security
19
      responses:
20
        "200":
21
          description: Server is up and running
22
        default:
23
          description: Something is wrong

作用域

OAuth 2 和 OpenID Connect 使用作用域来控制对各种用户资源的权限。例如，宠物商店的作用域可能包括 read_pets、write_pets、read_orders、write_orders、admin。在应用 security 时，与 OAuth 2 和 OpenID Connect 对应的条目需要指定特定操作所需的作用域列表（如果 security 在操作级别使用）或所有 API 调用（如果 security 在根级别使用）。

1
security:
2
  - OAuth2:
3
      - scope1
4
      - scope2
5
  - OpenId:
6
      - scopeA
7
      - scopeB
8
  - BasicAuth: []
  • 对于 OAuth 2，security 中使用的作用域必须事先在 securitySchemes 中定义。
  • 对于 OpenID Connect 发现，可能的作用域在 openIdConnectUrl 指定的发现端点中列出。
  • 其他方案（基本、Bearer、API 密钥和其他）不使用作用域，因此它们的 security 条目指定一个空数组 [] 代替。

不同的操作通常需要不同的作用域，例如读、写和管理。在这种情况下，您应该将作用域 security 应用于特定操作，而不是全局应用。

1
# Instead of this:
2
# security:
3
#   - OAuth2:
4
#       - read
5
#       - write
6


7
# Do this:
8
paths:
9
  /users:
10
    get:
11
      summary: Get a list of users
12
      security:
13
        - OAuth2: [read]     # <------
14
      ...
15


16
    post:
17
      summary: Add a user
18
      security:
19
        - OAuth2: [write]    # <------
20
      ...

使用多种身份验证类型

一些 REST API 支持多种身份验证类型。security 部分允许你使用逻辑 OR 和 AND 来组合安全要求，以达到预期的结果。security 使用以下逻辑

1
security: # A OR B
2
  - A
3
  - B
1
security: # A AND B
2
  - A
3
    B
1
security: # (A AND B) OR (C AND D)
2
  - A
3
    B
4
  - C
5
    D

也就是说，security 是哈希映射的数组，其中每个哈希映射包含一个或多个命名的安全方案。哈希映射中的项使用逻辑 AND 组合，数组项使用逻辑 OR 组合。通过 OR 组合的安全方案是可选项——在给定的上下文中可以使用任何一种。通过 AND 组合的安全方案必须在同一请求中同时使用。在这里，我们可以使用基本身份验证或 API 密钥。

1
security:
2
  - basicAuth: []
3
  - apiKey: []

在这里，API 要求在请求中包含一对 API 密钥。

1
security:
2
  - apiKey1: []
3
    apiKey2: []

在这里，我们可以使用 OAuth 2 或一对 API 密钥。

1
security:
2
  - oauth2: [scope1, scope2]
3
  - apiKey1: []
4
    apiKey2: []

参考

安全方案对象

安全要求对象

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

Swagger 开源
Swagger
专业工具
资源