繁體中文(香港)
  • openid connect
  • oidc
  • oidc configuration
  • openid-configuration
  • oauth

探索 OpenID Connect 配置:關鍵字段及其用途

探索 OpenID Connect 配置的關鍵字段和實際應用。

Yijun
Yijun
Developer

Stop wasting weeks on user auth
Launch secure apps faster with Logto. Integrate user auth in minutes, and focus on your core product.
Get started
Product screenshot

在當今的數碼世界中,身份驗證已成為保護網站和應用程式的核心組成部分。OpenID Connect(OIDC)是構建於 OAuth 2.0 協議之上的身份驗證層,提供了一種標準化且簡單的方法來驗證身份。

然而,正確整合 OIDC 可能讓人望而卻步,尤其是對於新手來說。一個好的起點通常是 OIDC 配置文件,通常位於 {authServerUrl}/.well-known/openid-configuration 網址,該文件包含了實施 OIDC 服務所需的所有必要詳細信息。

本指南旨在闡明此配置中的關鍵字段,幫助開發者理解其重要性和實際應用,以更好地將 OIDC 整合到他們的項目中。

分析 OIDC 配置字段

OIDC 配置類似於以下 JSON 文件:

接下來,我們將深入探討一些關鍵字段。

authorization_endpoint

在整合 OIDC 服務時,通常的第一步是處理應用程式中的用戶登錄請求。這個過程包括將用戶重定向至授權服務器的 authorization_endpoint。此端點是發送授權請求的服務器地址,引導用戶進入登錄頁面以進行身份驗證。

在向 authorization_endpoint 發出請求時,必須為每次授權配置額外的查詢參數:

  • response_type:指定返回的授權類型。這通常包括 "code"(用於授權碼流程)、"token"(用於隱式流程)、"id_token token" 或 "code id_token"(用於混合流程),可以在 OIDC 配置的 response_types_supported 字段中找到。
  • client_id:在應用註冊時,由授權服務器分配給應用的唯一標識符。此 ID 用於授權服務器識別發起請求的客戶端應用。
  • scope:定義所請求的訪問範圍,指定可訪問的資源或用戶信息。常用範圍包括 "openid"(必須)、"profile" 和 "email" 等。你可以在 OIDC 配置的 scopes_supported 字段中找到支持的範圍;不同的範圍應以空格分開。
  • redirect_uri:在登錄或授權後,授權服務器將用戶重定向回應用提供的 URI。此 URI 必須嚴格與應用註冊時提供的 URI 匹配。
  • state:隨機生成的字符串,用於保護客戶端避免跨站請求偽造攻擊。在授權請求和回調之間必須保持狀態的一致性以確保安全性。

這些參數允許開發者精確控制 OIDC 授權請求的行為,確保它們安全且滿足應用的需求。

完成對 authorization_endpoint 的請求並通過身份驗證後,用戶將被重定向至指定的 redirect_uri,其中將包含一個非常關鍵的查詢參數——code。此授權碼由授權服務器提供,是用戶身份驗證並授權應用訪問其信息的結果。

token_endpoint

token_endpoint 是由授權服務器用於將上述授權碼交換為訪問令牌和刷新令牌的服務器端點。在 OAuth 2.0 授權碼流程中,此步驟至關重要,因為它涉及將獲取的授權碼轉換為應用可用來訪問用戶受保護資源的實際訪問令牌。

以下是如何實現授權碼交換為訪問令牌的過程(請注意,此示例使用 client_secret_post 身份驗證方法。對於其他支持的身份驗證方法,請參照稍後對

token_endpoint_auth_methods_supported
字段的分析):

在此代碼中,我們首先使用 POST 方法向 token_endpoint 發送請求。內容類型設置為 application/x-www-form-urlencoded,這是大多數授權服務器所需的。請求體包括以下參數:

  • code:從授權服務器獲得的授權碼,通過用戶完成授權後返回的 redirect_uri 獲得。
  • redirect_uri:用於獲得授權碼的相同重定向 URI,用於驗證請求的合法性。
  • client_id:應用的客戶端標識符,用於識別發起請求的應用。
  • client_secret:應用的客戶端密鑰,用於驗證應用的身份。
  • grant_type:指定授權的類型,此處使用 "authorization_code",這表示訪問令牌是通過授權碼獲得。

此函數異步執行,返回包含訪問令牌的 JSON 對象,應用可以使用此令牌請求用戶數據或執行其他操作。

userinfo_endpoint

userinfo_endpoint 是由授權服務器用於獲取經身份驗證的用戶詳細信息的服務器端點。用戶成功授權並通過 token_endpoint 獲取訪問令牌後,應用可以請求此端點以訪問用戶的詳細信息,例如用戶名和電子郵件地址。獲取的具體信息取決於用戶在身份驗證請求中指定的 scope

在此函數中,我們首先使用 GET 方法請求 userinfo_endpoint,並在請求標頭中包含由 token_typeaccessToken 組成的 Authorization 字段。這是根據 OAuth 2.0 規範進行的標準操作,確保安全地檢索用戶信息。此外,通過訪問令牌訪問的用戶信息範圍完全取決於用戶在授權啟動時採用的 scope 參數值。例如,如果使用 email 範圍,則應答應包含用戶的電子郵件地址。

issuer & jwks_uri

發行者標識授權服務器的 URL,而 jwks_uri 提供用於驗證 JWT 簽名的 JSON Web 密鑰集合(JWKS)的 URI。驗證 JWT 的 issuer 和簽名是確保令牌安全性的基本步驟,但在實際

情況下,驗證過程通常還包括檢查令牌的有效期、受眾、授權範圍及其他重要字段。

以下代碼主要演示如何使用 issuerjwks_uri 一起驗證 JWT:

scopes_supported & claims_supported

claims_supportedscopes_supported 字段聲明授權服務器支持的用戶屬性(聲明)和訪問範圍(範圍)。它們幫助客戶端了解授權服務器支持哪些用戶屬性和訪問範圍,使客戶端能夠有效地構建授權請求並解析響應。

在構建授權請求時,客戶端可以根據應用的需求指定必要的 scopeScope 定義了客戶端請求訪問的資源和操作,例如 openidemailprofile 及其他。

需要注意的是,每次授權請求中可訪問的具體聲明取決於身份驗證請求開始時指定的範圍值。例如,email 範圍授予訪問用戶電子郵件地址的權限,而 phone 範圍提供訪問用戶電話號碼的權限。因此,客戶端在創建授權請求時應仔細選擇相關的範圍以符合應用的需求,以確保他們能夠檢索到必要的用戶屬性:

token_endpoint_auth_methods_supported

token_endpoint_auth_methods_supported
字段表明令牌端點支持的身份驗證方法。這些方法用於客戶端在利用授權碼交換訪問令牌時與授權服務器進行身份驗證。

在使用令牌端點進行身份驗證時,常用的身份驗證方法包括 client_secret_postclient_secret_basicclient_secret_jwt

  • client_secret_post:客戶端使用其客戶端標識符和客戶端密鑰構建表單編碼體,並將其作為請求體的一部分發送。我們在上述 token_endpoint 節中已經看到此方法的示例。

  • client_secret_basic:客戶端使用其客戶端標識符和客戶端密鑰構建基本身份驗證標頭,然後將其添加至請求頭中。

  • client_secret_jwt:客戶端使用 JWT(JSON Web Token)作為客戶端聲明進行身份驗證。此 JWT 包含客戶端標識符及一些附加元數據,並使用客戶端密鑰簽名。授權服務器收到請求後,通過驗證 JWT 的簽名來驗證客戶端身份。

在實際應用中,客戶端需要根據授權服務器支持的方法選擇合適的身份驗證方法,並確保正確地將身份驗證信息添加到請求中,以安全地將授權碼交換為訪問令牌。

總結

我們現在已經探索了 OIDC 配置中的關鍵字段,重點關注它們的用途和應用。了解這些詳細信息將提高你對 OpenID Connect 的理解,使你能夠更有效地將其整合並利用於你的項目中。掌握這些知識後,你將更好地運用 OIDC 的全部潛力,為用戶提供更安全和高效的身份驗證解決方案。

Logto 作為基於 OIDC 的身份驗證服務,提供多種語言的完整開發套件(SDK)以及眾多整合教程,使你在短短幾分鐘內就可以無縫整合 OAuth / OIDC 登錄到你的應用中。如果你正在尋找一個可靠且易於使用的 OIDC 服務,今天就試試 Logto 吧!