關於這項作業
如果要將 Liberty 伺服器配置成接受 JWT 記號作為鑑別記號,請啟用 openidConnectClient-1.0 特性,並設定 inboundPropagation="required",然後配置信任儲存庫和 SSL。您可以選擇性地指定其他的 JWT
配置,例如:使用者登錄、鑑別過濾器,以及「聲明至主體」對映。配置成以 JWT 作為鑑別記號,類似於在 Liberty 中配置「OpenID Connect 用戶端」。
任何授信方只要獲得 JWT 記號,即可使用該記號取得
Liberty 中相關聯資源的存取權。
Liberty 資源伺服器會驗證 JWT 記號,並從 JWT 記號建立受鑑別的主體。如果要接受 JWT 記號作為鑑別記號,該 JWT 記號必須包含
iss、
sub 和
exp
聲明,且必須以 RS256 或 HS256 演算法來簽署。不支援加密的 JWT。下列範例顯示解碼後的 JWT 有效負載:
{
"iss":"https://idp.acme.com:8020/jwt",
"sub":"marissa@acme.com",
"exp":1385066178,
"aud":"https://resource.acme.com/services",
"iat":1385062578,
“groupIds”: [
“group1”, “group2”
]
}
- 在 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 元素,並設定
inboundPropagation="required"。如需其他 openidConnectClient 屬性的相關資訊,請參閱 OpenID Connect 用戶端。
下列的配置範例假設 JWT 記號發證者支援「JSON Web 金鑰 (JWK)」,並且是以 RS256 演算法來簽署。
<openidConnectClient id="RS" inboundPropagation="required"
jwkEndpointUrl="https://acme.com/jwtserver/jwk" signatureAlgorithm="RS256"
issuerIdentifier="https://idp.acme.com:8020/jwt" >
</openidConnectClient>
- 配置信任儲存庫以包含 JWK 端點憑證,使 Liberty 伺服器可以與該 JWK 端點建立 SSL 連線。信任儲存庫配置在
server.xml 檔中的 keyStore 元素上。 在您配置 SSL 以參照這個信任儲存庫之後,您可以將 SSL 配置設定成伺服器的預設 SSL 配置,或在
openidConnectClient 元素的 sslRef 屬性上,指定信任儲存庫 ID。
如果 JWT 發證者不支援 JWK,並改用 X.509 憑證來簽署 JWT,請將發證者的
X.509 憑證匯入至信任儲存庫。在 openidConnectClient 元素的
trustStoreRef 屬性上指定信任儲存庫 ID,並參照
trustAliasName 屬性上的憑證。
如果共用密碼金鑰與
HMAC-SHA256 演算法搭配使用來簽署 JWT,請在 sharedKey
或 clientSecret 屬性上定義共用密碼金鑰。
如需信任儲存庫或金鑰儲存庫的相關資訊,請參閱在 Liberty 中啟用 SSL 通訊。
- 配置 openidConnectClient 元素的 issuerIdentifier 屬性,以符合 JWT 發證者
iss 聲明。
比方說,如果 JWT 記號含有 "iss":"https://idp.acme.com:8020/jwt",請設定 issuerIdentifier="https://idp.acme.com:8020/jwt"。
- 選擇性的: 配置使用者登錄。 依預設,會使用已驗證的 JWT 聲明,直接建立呼叫端受鑑別的主體,而不將 JWT 對映至使用者,因此不需要使用者登錄。
不過,如果 openidConnectClient 元素的 mapIdentityToRegistryUser 屬性設為 true,則授權伺服器必須針對適當身分傳回一個使用者項目,這樣鑑別和授權才會成功。如需配置使用者登錄的相關資訊,請參閱在 Liberty 中配置使用者登錄。
- 選擇性的: 依照鑑別過濾器中的說明,配置鑑別過濾器。
如果您配置鑑別過濾器,請參照
openidConnectClient 元素之 authFilterRef 屬性上的鑑別過濾器。
如果 openidConnectClient 元素中沒有配置
authFilterRef 屬性,當嘗試發出任何未經鑑別的要求時,這個 openidConnectClient 元素都會加以鑑別。
- 選擇性的: 配置多個 openidConnectClient
元素和多個鑑別過濾器,以便將 Liberty 資源伺服器配置成與多個 JWT 發證者或鑑別 Proxy 伺服器一起運作。
每一個 openidConnectClient 元素各定義與一個
JWT 發證者或鑑別 Proxy 之間的一項信任關係,並且會參照一個鑑別過濾器。
- 選擇性的: 定義「JWT 聲明至鑑別主體」對映規則
Liberty 資源伺服器使用 JWT 聲明來建立鑑別主體,且您可以在下列
openidConnectClient 元素屬性上,定義 JWT 聲明如何對映至主體:
- userIdentifier
- userUniqueIdentifier
- groupIdentifier
- realmName
- realmIdentifier
如果同時配置了
realmName 和
realmIdentifier,則會優先採用
realmName,並且忽略
realmIdentifier。
如果您沒有定義「聲明至主體」對映,則會套用下列的預設對映規則:
- 主體 (sub) 聲明用來作為使用者的主體名稱和唯一安全名稱。
- 發證者 (iss) 聲明是預設領域,並且作為主體領域。如果 JWT 記號中包含
realmName 聲明,則會以 realmName 聲明(而非 iss 聲明)作為主體領域。
- 選擇性的: 配置單一登入 Cookie。 Liberty 伺服器會預期每一項要求都會提供有效的 JWT 記號,而不會建立或使用單一登入 Cookie 來進行鑑別。如果要建立單一登入 Cookie,請在
openidConnectClient 元素上設定 authnSessionDisabled="false"。
- 選擇性的: 將 Liberty 伺服器配置成接受 JWT 記號。Web 用戶端可以使用下列其中一種方法,將 JWT 記號放在資源要求中傳送給 Liberty 資源伺服器。如果 JWT 記號是放在
Authorization 欄位或表單編碼的內文參數中傳送,則不需額外的伺服器配置。
重要: 用戶端不得在每一項要求中使用多個方法來傳送記號。如果配置了 headerName 屬性,則會忽略放在
Authorization 標頭欄位或表單編碼的內文參數中傳送的記號。如果未配置
headerName 屬性,則會先搜尋 Authorization
標頭,再搜尋 access_token 參數。
- 配置 JWT 對象。 如果要定義授信對象清單,請在
openidConnectClient 元素上配置 audiences 屬性。
有效的 JWT 記號必須滿足下列其中一項條件:
- 如果配置了 audiences 屬性,對象 (aud)
聲明值必須是所配置的其中一個對象。如果要忽略對象檢查,請將
audiences 設為 ALL_AUDIENCES。
- 如果沒有配置 audiences 屬性,但是 JWT 記號包含
aud 聲明,且它是有效的 URL,資源服務 URL 必須以
aud 值作為字首。
比方說,下列對象是有效的,因為資源 URL 的開頭是
aud 聲明值:
- 對象聲明:"aud":"https://<server>:<port>/something"
- 資源 URL:https://<server>:<port>/something/specific
下列對象是無效的,因為資源 URL 的開頭不是
aud 聲明值。
- 對象聲明:"aud":"https://<server>:<port>/something/specific"
- 資源 URL:https://<server>:<port>/something
- 選擇性的: 實作
com.ibm.wsspi.security.oauth.UserCredentialResolver 服務程式設計介面
(SPI),以便以程式設計方式將 JWT 記號對映至主體。
如需介面的相關資訊,請參閱程式設計介面 (Javadoc)中,或產品隨附於 ${wlp.install.dir}/dev/spi/ibm/ 目錄的 Java 說明文件中,所提供的 com.ibm.wsspi.security.oauth.UserCredentialResolver SPI 資訊。