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 編輯器 3.14.8 中新增了對 OpenID Connect 探索的支援。

找不到您要找的東西嗎？詢問社群
發現錯誤了嗎？請告訴我們