在 Liberty 中配置「OpenID Connect 用戶端」
您可以將 Liberty 伺服器配置成當作「OpenID Connect 用戶端」或「依賴方」,以充分利用 Web 單一登入,以及使用「OpenID Connect 提供者」作為身分提供者。
關於這項作業
您可以在 Liberty 中啟用 openidConnectClient-1.0 特性,外加其他的配置資訊,將 Liberty 伺服器配置成作為「OpenID Connect 用戶端」。
程序
- 在 server.xml 檔中新增 openidConnectClient-1.0
Liberty 特性和其他任何所需特性。openidConnectClient-1.0 特性也需要 ssl-1.0 特性。在 server.xml 檔中,將下列元素宣告新增到 featureManager 元素內:
<feature>openidConnectClient-1.0</feature> <feature>ssl-1.0</feature>
- 配置 openidConnectClient 元素。下列範例是使用預設 Liberty 伺服器 OpenID Connect 提供者的最低配置。
用戶端必須在給定的 URL 型樣中提供一個已配置的應用程式,且其可以處理來自「OpenID Connect 提供者」的重新導向要求。這個 URL 也必須完全符合用戶端向 OP 登錄的重新導向 URL。
避免問題: 如果您使用出埠 Proxy,請注意, OpenID Connect RP 不提供任何方法來自動透過 Proxy 主機遞送要求。如果您必須使用 Proxy 來存取「OpenID Connect 提供者 (OP)」,您針對任何 OP 相關 URL 內容所輸入的值,必須包含 Proxy 主機和埠,而不是包含外部 OP 主機和埠。
在大部分情況下,您可以用 Proxy 主機和埠,取代 OP 主機和埠。RP 和用戶端(瀏覽器或應用程式)必須都能看見您所輸入的 URL。對於如何判斷所要使用的正確 URL,如需進一步指引,請聯絡您的 Proxy 管理者。
在本例中,用戶端預期的 SSL 埠設為 443。
<openidConnectClient id="client01" clientId="client01" clientSecret="{xor}LDo8LTor" authorizationEndpointUrl="https://server.example.com:443/oidc/endpoint/OidcConfigSample/authorize" tokenEndpointUrl="https://server.example.com:443/oidc/endpoint/OidcConfigSample/token"> </openidConnectClient>
在這個最基本的配置範例中,會假設下列預設值:- scope=openid profile:需要 openid 範圍,且您可以使用 scope 屬性來編輯必要範圍。比方說,您可以將必要 scope 變更為 openid profile email。
- 此 RP 會向 OP 將其重新導向 URL 登錄為 https://<host name>:<ssl port>/oidcclient/redirect/client01,其中,會自動解析主機名稱和 ssl 埠,且 client01 是 openidConnectClient 配置元素的 ID。若有 Proxy 位於 RP 前面,您可以使用 redirectToRPHostAndPort 屬性置換主機名稱和埠,並將 redirectToRPHostAndPort 設為 https://<host name>:<ssl port>。
- 配置使用者登錄。依預設,OP 傳回的使用者身分不會對映至登錄使用者,因此不需在登錄中配置任何使用者。不過,如果 openidConnectClient 元素的 mapIdentityToRegistryUser 屬性設為 true,則 OP 所傳回的適當身分必須有一個使用者項目,這樣鑑別和授權才會成功。如需配置使用者登錄的相關資訊,請參閱在 Liberty 中配置使用者登錄。
- 配置伺服器的信任儲存庫,以包含支援的「OpenID Connect 提供者」簽章者憑證。如需金鑰儲存庫的相關資訊,請參閱在 Liberty 中啟用 SSL 通訊
- 修改伺服器的 SSL 配置,以使用所配置的信任儲存庫。
<sslDefault sslRef="DefaultSSLSettings" /> <ssl id="DefaultSSLSettings" keyStoreRef="myKeyStore" trustStoreRef="myTrustStore" /> <keyStore id="myKeyStore" password="{xor}EzY9Oi0rJg==" type="jks" location="${server.config.dir}/resources/security/BasicKeyStore.jks" /> <keyStore id="myTrustStore" password="{xor}EzY9Oi0rJg==" type="jks" location="${server.config.dir}/resources/security/BasicTrustStore.jks" />
OpenID Connect 是配置成使用伺服器指定的預設 SSL 配置。因此,伺服器的預設 SSL 配置必須使用配置給 OpenID Connect 的信任儲存庫。
除了如範例所示使用 SSL 預設配置,也可以在 sslDefault 元素上利用 outboundSSLRef 屬性來配置出埠預設 SSL 配置。如果指定了出埠預設屬性,進行出埠連線時,會使用 outboundSSLRef 屬性指定的 SSL 配置。您可以置換預設值,並使用 SSL 配置中的出埠 SSL 過濾器,來指定用於出埠連線的主機和埠。如需相關資訊,請參閱SSL 配置的出埠過濾器和配置出埠通訊的 SSL 設定。
- 選用:配置協力廠商 OpenID Connect 提供者。
如果要將 Liberty OpenID Connect 用戶端配置成使用協力廠商「OpenID Connect 提供者」(例如 Microsoft Azure 或 Google),您必須配置下列屬性。如果要取得屬性值,可呼叫 OP 的探索端點,這會在 /.well-known/openid-configuration 字串配上發證者而形成的路徑中提供 JSON 文件。
- 將 jwkEndpointUrl 屬性設為 OP JSON Web 金鑰集 JWK 文件的 URL,這在探索檔案中是定義成 jwks_uri。比方說,如果要使用 Google 的 OP,您可以設定 jwkEndpointUrl = "https://www.googleapis.com/oauth2/v2/certs"。
- 將 issuerIdentifier 屬性設為探索檔案中所定義的 issuer。如果 ID 記號沒有包含此值來作為 iss 聲明,則會被拒絕。比方說,如果您使用 Google 作為您的 OP,您可以設定 issuerIdentifier="accounts.google.com"。
- 設定 signatureAlgorithm="RS256"。Liberty OpenID Connect 用戶端的預設簽章演算法是 HS256。
- 將 userIdentityToCreateSubject 屬性設為供應商 ID 記號所使用的聲明名稱,以代表使用者的唯一 ID。比方說,如果您使用 Google 的 OP,可設定 userIdentityToCreateSubject ="email",如果您使用 Microsoft Azure,可設定 userIdentityToCreateSubject ="upn" 或 userIdentityToCreateSubject ="unique_name"。
- 將 groupIdentifier 屬性設為代表使用者的群組成員資格或角色的聲明名稱。比方說,如果您使用 Microsoft Azure,可設定 groupIdentifier="groups"。
如需其他的「OpenID Connect 用戶端」配置選項,請參閱 OpenID Connect 用戶端。
- 選用:鑑別過濾器。
當啟用 openidConnectClient-1.0 特性時,如果沒有使用 authFilterRef 屬性來配置 openidConnectClient 元素,任何未經鑑別的要求,都會經由 OpenID Connect 提供者來鑑別。
如需配置鑑別過濾器的相關資訊,請參閱鑑別過濾器。
- 支援多個 OpenID Connect 提供者。
您可以建立多個 openidConnectClient 元素和多個鑑別過濾器,將 Liberty 配置成多個「OpenID Connect 提供者」的「OpenID Connect 依賴方」。每一個 openidConnectClient 元素各與一個「OpenID Connect 提供者」之間定義一項「單一登入」關係,並使用 authFilterRef 屬性,來參照一個「鑑別過濾器」。
- 配置支援的「ID 記號」簽章演算法。
您可以配置 Liberty OpenID Connect 用戶端,在「ID 記號」中支援 RS256 簽章演算法。Liberty OpenID Connect 用戶端的預設簽章演算法是 HS256。如果您設定 signatureAlgorithm="RS256",將 RS256 配置成「ID 記號」的簽章演算法,除非 OP 支援 JWK 端點,您必須同時配置 trustStoreRef 和 trustAliasName。
- 選用:配置「隱含的」授權類型。
openidConnectClient-1.0 特性使用「授權碼」授權類型來要求使用者鑑別記號,您可以在 server.xml 檔中新增 grantType="implicit",即可配置 Liberty openidConnectClient-1.0 特性來使用「隱含的」授權類型。如果您的 Liberty 伺服器和 OpenID Connect 提供者位於不同的防火牆,則必須使用這個配置選項。
- 選用:在處理「ID 記號」之後,Liberty OpenID Connect 依賴方會自動建立單一登入 (SSO) 記號。您可以新增 disableLtpaCookie="true" 配置內容,將 Liberty 配置成不為伺服器建立 SSO 記號,或不為以 OpenID Connect 保護的資源建立 SSO 記號。如果設定 disableLtpaCookie="true",則 Liberty OpenID Connect 用戶端只接受先前已經過所配置之 OpenID Connect 提供者鑑別的鑑別要求,且鑑別階段作業生命期限會限定為「ID 記號」的生命期限。
- 選用:您可以將「OpenID Connect 用戶端」配置成選擇性地接受有效的 OAuth 2.0 載送存取記號作為鑑別記號,而不將要求重新導向至 OpenID Connect 提供者。如果要求含有有效的 OAuth 2.0 載送存取記號,Liberty OpenID Connect 用戶端會自動驗證該存取記號,並根據記號驗證結果,建立一個已鑑別的主體。如果要求沒有包含存取記號,或存取記號無效,Liberty OpenID Connect 用戶端會繼續將使用者重新導向至 OpenID Connect 提供者。此功能可讓 Liberty 伺服器同時處理瀏覽器用戶端和非瀏覽器用戶端 (例如 RESTful 用戶端)。您可以新增 inboundPropagation=”supported” 至配置,以啟用這項功能。
如果您的主機環境不容許存取 /oidcclient 環境定義根目錄,請配置 oidcClientWebapp 元素,以修改環境定義根目錄。
依預設,Liberty OpenID Connect 用戶端的重新導向 Servlet 會接聽 /oidcclient 環境定義根目錄,且其重新導向 URL 格式是 https://<host_name>:<ssl_port>/oidcclient/redirect/<configuration_ID>。 如果您無法使用這個環境定義根目錄,請在伺服器配置中設定不同的環境定義根目錄。
比方說,如果您的主機環境需要您使用 /acme/openid 環境定義根目錄,請新增下列元素:<oidcClientWebapp contextPath="/acme/openid" />
產生的重新導向 URL 格式是 https://<host_name>:<ssl_port>/acme/openid/redirect/<configuration_ID>。
結果
次主題
- 呼叫 OpenID Connect 的授權端點
在 OpenID Connect 中,授權端點會處理使用者的鑑別和授權。 - 呼叫 OpenID Connect 的內部檢查端點
內部檢查端點可讓存取記號的持有者向簽發存取記號的「OpenID Connect 提供者」,要求存取記號的一組相關 meta 資料。存取記號必須是透過 OpenID Connect 或 OAuth 鑑別所取得的存取記號。 呼叫 OpenID Connect 的撤銷端點
撤銷端點可讓存取記號或更新記號的持有者,通知 OpenID Connect 提供者,使其得知所簽發的記號不再需要而必須撤銷。撤銷端點可以撤銷透過 OpenID Connect 或 OAuth 鑑別取得的記號。呼叫 OpenID Connect 的登出端點
用戶端會利用登出端點,來清除 Web 瀏覽器的提供者端階段作業和 Cookie。- 呼叫 OpenID Connect 的階段作業管理端點
階段作業管理端點可讓「OpenID Connect 依賴方」監視使用者在特定「OpenID Connect 提供者 (OP)」的登入狀態,同時將網路資料流量降至最低。藉助於階段作業管理端點,「依賴方 (RP)」可以使已登出「OpenID Connect 提供者」的使用者登出。 - 呼叫 OpenID Connect 的記號端點
在 OpenID Connect 的「授權碼流程」中,記號端點供用戶端用來取得 ID 記號、存取記號和更新記號。 - 呼叫 OpenID Connect 的 UserInfo 端點
UserInfo 端點會針對接受 OpenID Connect 鑑別程序鑑別的使用者,傳回其相關聲明。

檔名:twlp_config_oidc_rp.html