OAS 3 本指南适用于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请参阅我们的 OpenAPI 2.0 指南。

身份验证和授权

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 安全方案（包括基本、承载和其他方案）的伞形类型，scheme关键字表示方案类型。
  • API 密钥现在可以发送in: cookie。
  • 添加了对 OpenID Connect 发现 (type: openIdConnect) 的支持。
  • OAuth 2 安全方案现在可以定义多个flows。
  • OAuth 2 流已重命名以匹配 OAuth 2 规范：accessCode现在是authorizationCode，application现在是clientCredentials。

描述安全

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

步骤 1. 定义 securitySchemes

API 使用的所有安全方案都必须在全局components/securitySchemes部分中定义。本部分包含命名安全方案的列表，其中每个方案可以是type安全方案的其他必需属性取决于type。以下示例展示了如何定义各种安全方案。BasicAuth、BearerAuth 名称和其他名称是任意的名称，将在规范中的其他地方使用它们来引用这些定义。
components:
  securitySchemes:

    BasicAuth:
      type: http
      scheme: basic

    BearerAuth:
      type: http
      scheme: bearer

    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

    OpenID:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration

    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants access to admin operations

步骤 2. 应用安全

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

# The syntax is:
# - scheme name:
#     - scope 1
#     - scope 2
对于每个方案，您都会指定 API 调用所需的安全性范围列表（请参阅 以下）。范围仅用于 OAuth 2 和 OpenID Connect 发现；其他安全方案使用空数组[]代替。全局security可以在各个操作中被覆盖，以使用不同的身份验证类型、不同的 OAuth/OpenID 范围，或根本不进行身份验证
paths:
  /billing_info:
    get:
      summary: Gets the account billing info
      security:
        - OAuth2: [admin]   # Use OAuth with a different scope
      responses:
        '200':
          description: OK
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope

  /ping:
    get:
      summary: Checks if the server is running
      security: []   # No security
      responses:
        '200':
          description: Server is up and running
        default:
          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在根级别使用）所需的范围列表。
security:
  - OAuth2:
      - scope1
      - scope2
  - OpenId:
      - scopeA
      - scopeB
  - BasicAuth: []
  • 在 OAuth 2 的情况下，security中使用的范围必须在securitySchemes中预先定义。
  • 在 OpenID Connect 发现的情况下，可能的范围列在由openIdConnectUrl指定的发现端点中。
  • 其他方案（基本、承载、API 密钥和其他方案）不使用范围，因此它们的security条目指定一个空数组[]代替。
不同的操作通常需要不同的范围，例如读取与写入与管理员。在这种情况下，您应该将范围化的security应用于特定操作，而不是全局应用。
# Instead of this:
# security:
#   - OAuth2:
#       - read
#       - write

# Do this:
paths:
  /users:
    get:
      summary: Get a list of users
      security:
        - OAuth2: [read]     # <------
      ...

    post:
      summary: Add a user
      security:
        - OAuth2: [write]    # <------
      ...

使用多种身份验证类型

一些 REST API 支持多种身份验证类型。security部分允许您使用逻辑 OR 和 AND 来组合安全性要求以实现所需的结果。security使用以下逻辑
security:    # A OR B
  - A
  - B
security:    # A AND B
  - A
    B

security:    # (A AND B) OR (C AND D)
  - A
    B
  - C
    D
也就是说，security是一个哈希映射数组，其中每个哈希映射包含一个或多个命名安全方案。哈希映射中的项使用逻辑 AND 组合，而数组项使用逻辑 OR 组合。通过 OR 组合的安全方案是备选方案 - 在给定上下文中可以使用任何一个。通过 AND 组合的安全方案必须在同一个请求中同时使用。在这里，我们可以使用基本身份验证或 API 密钥
security:
  - basicAuth: []
  - apiKey: []
在这里，API 要求在请求中包含一对 API 密钥
security:
  - apiKey1: []
    apiKey2: []
在这里，我们可以使用 OAuth 2 或一对 API 密钥
security:
  - oauth2: [scope1, scope2]
  - apiKey1: []
    apiKey2: []

参考

安全方案对象

安全要求对象

  

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