跳过内容

OpenID Connect 发现

OpenID Connect (OIDC) 是基于 OAuth 2.0 协议构建的身份层，并得到某些 OAuth 2.0 提供商（例如 Google 和 Azure Active Directory）的支持。它定义了一个登录流程，使客户端应用程序能够验证用户身份，并获取有关该用户的信息（或“声明”），例如用户名、电子邮件等。用户身份信息编码在一个安全的 JSON Web Token (JWT) 中，称为 ID 令牌。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.4
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 发现的支持。

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

© . All rights reserved.