配置 OpenID Connect 的「JSON Web 記號」鑑別

您可以配置 Liberty 伺服器，以接受「JSON Web 記號 (JWT)」記號作為來自授信鑑別 Proxy、授信服務用戶端或 OAuth 授權伺服器的鑑別記號。

{
	"iss":"https://idp.acme.com:8020/jwt",
	"sub":"marissa@acme.com",
	"exp":1385066178,
	"aud":"https://resource.acme.com/services",
	"iat":1385062578,
	"groupIds": [
	    "group1", "group2"
	 ]
}

1. 將 openidConnectClient-1.0 Liberty 特性及任何其他必要特性新增至 server.xml 檔。 最起碼 openidConnectClient-1.0 特性需要 transportSecurity-1.0 特性。 在 server.xml 檔中的 featureManager 元素內新增下列元素宣告:

   <feature>openidConnectClient-1.0</feature>
   <feature>transportSecurity-1.0</feature>

2. 配置 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>

3. 配置信任儲存庫以包含 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，請在 clientSecret 屬性上定義共用密碼金鑰。

   如需信任儲存庫或金鑰儲存庫的相關資訊，請參閱 在 Liberty 中啟用 SSL 通訊。

4. 配置 openidConnectClient 元素的 issuerIdentifier 屬性，以符合 JWT 發證者 iss 要求。

   比方說，如果 JWT 記號含有 "iss":"https://idp.acme.com:8020/jwt"，請設定 issuerIdentifier="https://idp.acme.com:8020/jwt"。

5. 選用: 配置使用者登錄。
   依預設，會使用已驗證的 JWT 聲明，直接建立呼叫端受鑑別的主體，而不將 JWT 對映至使用者，因此不需要使用者登錄。

   不過，如果 openidConnectClient 元素的 mapIdentityToRegistryUser 屬性設為 true，則授權伺服器必須針對適當身分傳回一個使用者項目，這樣鑑別和授權才會成功。 如需配置使用者登錄的相關資訊，請參閱 在 Liberty 中配置使用者登錄。

6. 選用項目: 依照 鑑別過濾器中的說明來配置鑑別過濾器。

   如果您配置鑑別過濾器，請參照 openidConnectClient 元素之 authFilterRef 屬性上的鑑別過濾器。

   如果 openidConnectClient 元素中沒有配置 authFilterRef 屬性，當嘗試發出任何未經鑑別的要求時，這個 openidConnectClient 元素都會加以鑑別。

7. 選用: 配置多個 openidConnectClient 元素和多個鑑別過濾器，將 Liberty 資源伺服器配置成使用多個 JWT 發證者或鑑別 Proxy 伺服器。

   每一個 openidConnectClient 元素各定義與一個 JWT 發證者或鑑別 Proxy 之間的一項信任關係，並且會參照一個鑑別過濾器。

8. 選用項目: 定義用於將 JWT 聲明對映至鑑別主體的規則。
   Liberty 資源伺服器使用 JWT 聲明來建立鑑別主體，您可以在下列 openidConnectClient 元素屬性上定義如何將 JWT 聲明對映至主體:

   • userIdentifier
   • userUniqueIdentifier
   • groupIdentifier
   • realmName
   • realmIdentifier

   如果同時配置了 realmName 和 realmIdentifier，則會優先採用 realmName，並且忽略 realmIdentifier。

   如果您沒有定義「聲明至主體」對映，則會套用下列的預設對映規則：

   • 主體 (sub) 聲明用來作為使用者的主體名稱和唯一安全名稱。
   • 發證者 (iss) 聲明是預設網域範圍，並且作為主體網域範圍。 如果 JWT 記號中包含 realmName 聲明，則會以 realmName 聲明（而非 iss 聲明）作為主體網域範圍。
9. 選用項目: 配置單一登入 Cookie。
   Liberty 伺服器預期每一個要求都會提供有效的 JWT 記號，且不會建立或使用單一登入 Cookie 來進行鑑別。 如果要建立單一登入 Cookie，請在 openidConnectClient 元素上設定 authnSessionDisabled="false"。
10. 選用: 配置 Liberty 伺服器來接收 JWT 記號。 Web 用戶端可以使用下列其中一種方法，將資源要求中的 JWT 記號傳送至 Liberty 資源伺服器。 如果 JWT 記號在 Authorization 欄位或表單編碼內文參數中傳送，則不需要其他伺服器配置。
    重要事項: 用戶端在每一個要求中不得使用多個方法來傳輸記號。 如果配置了 headerName 屬性，則會忽略放在 Authorization 標頭欄位或表單編碼的內文參數中傳送的記號。 如果未配置 headerName 屬性，則會先搜尋 Authorization 標頭，再搜尋 access_token 參數。
    • 將記號放在 Authorization 要求標頭欄位中傳送。

      GET /resource HTTP/1.1
      Host: server.example.com
      Authorization: Bearer mF_9.B5f-4.1JqM
      

    • 將要求實體內文中的記號傳送為表單編碼內文參數。

      POST /resource HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
      access_token=mF_9.B5f-4.1JqM
      

    • 在 Liberty中配置授信標頭名稱，以在自訂要求標頭欄位上傳送記號。

      如果要配置授信標頭名稱，請在 openidConnectClient 元素上設定 headerName="<myJwtHeaderName>" 。 例如，如果您設定 headerName="jwt"，您可以將記號放在 jwt 標頭欄位中傳送，如下列範例所示：

      GET /resource HTTP/1.1
      Host: server.example.com
      jwt: mF_9.B5f-4.1JqM

11. 配置 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
12. 選用: 實作 com.ibm.wsspi.security.oauth.UserCredentialResolver 服務程式設計介面 (SPI) ，以程式設計方式將 JWT 記號對映至主體。

    如需介面的相關資訊，請參閱 程式設計介面 中或 ${wlp.install.dir}/dev/spi/ibm/ 目錄中隨產品提供的 Java 說明文件中的 com.ibm.wsspi.security.oauth.UserCredentialResolver SPI 資訊。