OpenID Connect 发现

OpenID Connect (OIDC) 是建立在 OAuth 2.0 协议之上的身份层，并受到某些 OAuth 2.0 提供程序（如 Google 和 Azure Active Directory）的支持。它定义了一个登录流程，使客户端应用程序能够对用户进行身份验证，并获取有关该用户的信息（或“声明”），例如用户名、电子邮件等。用户身份信息被编码在称为 ID 令牌的安全 JSON Web 令牌 (JWT) 中。OpenID Connect 定义了一种发现机制，称为 OpenID Connect 发现，其中 OpenID 服务器在其众所周知的 URL（通常是）上发布其元数据

https://server.com/.well-known/openid-configuration

此 URL 返回 OpenID/OAuth 端点、支持的范围和声明、用于签署令牌的公钥以及其他详细信息的 JSON 列表。客户端可以使用此信息来构建对 OpenID 服务器的请求。字段名称和值在 OpenID Connect 发现规范中定义。以下是返回的数据示例

1
{
2
  "issuer": "https://example.com/",
3
  "authorization_endpoint": "https://example.com/authorize",
4
  "token_endpoint": "https://example.com/token",
5
  "userinfo_endpoint": "https://example.com/userinfo",
6
  "jwks_uri": "https://example.com/.well-known/jwks.json",
7
  "scopes_supported": ["pets_read", "pets_write", "admin"],
8
  "response_types_supported": ["code", "id_token", "token id_token"],
9
  "token_endpoint_auth_methods_supported": ["client_secret_basic"],
10
  ...,
11
}

描述 OpenID Connect 发现

OpenAPI 3.0 允许您按如下方式描述 OpenID Connect 发现

1
openapi: 3.0.0
2
---
3
# 1) Define the security scheme type and attributes
4
components:
5
  securitySchemes:
6
    openId: # <--- Arbitrary name for the security scheme. Used to refer to it from elsewhere.
7
      type: openIdConnect
8
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
9

10
# 2) Apply security globally to all operations
11
security:
12
  - openId: # <--- Use the same name as specified in securitySchemes
13
      - pets_read
14
      - pets_write
15
      - admin

第一部分 components/securitySchemes 定义安全方案类型 (openIdConnect) 和发现端点的 URL (openIdConnectUrl)。与 OAuth 2.0 不同，您无需在 securitySchemes 中列出可用的范围 – 客户端应该改为从发现端点读取它们。security 部分随后将选择的安全方案应用于您的 API。此处需要列出 API 调用所需的实际范围。这些可能是发现端点返回的范围的子集。如果不同的 API 操作需要不同的范围，您可以在操作级别而不是全局应用 security。这样，您可以为每个操作列出相关范围

1
paths:
2
  /pets/{petId}:
3
    get:
4
      summary: Get a pet by ID
5
      security:
6
        - openId:
7
          - pets_read
8
      ...
9

10
    delete:
11
      summary: Delete a pet by ID
12
      security:
13
        - openId:
14
          - pets_write
15
      ...

相对发现 URL

openIdConnectUrl 可以指定为相对于服务器 URL，如下所示

1
servers:
2
  - url: https://api.example.com/v2

1
components:
2
  securitySchemes:
3
    openId:
4
      type: openIdConnect
5
      openIdConnectUrl: /.well-known/openid-configuration

相对 URL 根据 RFC 3986 解析。在上面的示例中，它将解析为 https://api.example.com/.well-known/openid-configuration。

Swagger UI 支持

Swagger UI v. 3.38.0 和 Swagger Editor 3.14.8 中添加了对 OpenID Connect 发现的支持。

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