[16.0.0.4 以及更新版本]

Liberty 中建置「JSON Web 記號」

您可以採程式設計方式來建置「JSON Web 記號 (JWT)」的記號,作法是在伺服器配置中配置 JWT 建置器元素,並在您的應用程式中實作 com.ibm.websphere.security.jwt.JwtBuildercom.ibm.websphere.security.jwt.JwtToken API。

關於這項作業

如需 JWT API 的相關資訊,請參閱 JSON Web 記號 Java 說明文件,或產品之 ${wlp.install.dir}/dev 目錄中所包含的 API 說明文件。

程序

  1. [18.0.0.1 以及更新版本]從 JWT 記號產生端點取得 JWT 記號。
    1. 不需程式設計,即可利用 jwt-1.0 特性的端點來取得記號。
    2. 如果您沒有在要求中包含認證,則會鑑別您的認證,以存取位於 https://<host>:<port>/jwt/api/ibm/<configId>/token 的端點。 在鑑別成功之後,會以 JSON 形式傳回 MP-JWT 格式的記號。記號會包含使用者的使用者和群組,如同伺服器的使用者登錄中所記錄的一樣。
    3. server.xml 檔中具有 <configId> ID 之 JWTBuilder 元素的屬性,來設定其他記號屬性,例如,發證者和有效期限。
    4. 如果您沒有在 server.xml 檔中定義 JWTBuilder 元素,請使用 defaultJWT 作為 <configId> ID。 可用的「JWT 建置器」配置屬性可在 jwtBuilder - JWT 建置器 (jwtBuilder) 中找到。
  2. 以程式設計方式,在 Liberty 中建置 JSON Web 記號。
  3. server.xml 檔中,新增 jwt-1.0 特性。
    <featureManager>
        <feature>jwt-1.0</feature>
        ...
    </featureManager>
  4. 修改 jwtBuilder 元素,以配置 JWT 建置器。

    如需您可以配置之 jwtBuilder 屬性的相關資訊,請參閱 JWT 建置器 (jwtBuilder)

    當您新增 jwt-1.0 特性,並儲存您的變更時,Liberty 會新增下列的預設 jwtBuilder 元素。
    <jwtBuilder id="defaultJWT">
    </jwtBuilder>
    在這項預設配置中,假設有下列值:
    • exp 聲明為記號建立時間後的 2 個小時。您可以在 expiry 屬性上配置此值。
    • iss 聲明設為 https://<host_name>:<ssl_port>/jwt/defaultJWT。 請在 issuer 屬性上配置發證者。
    • 使用 RS256 演算法以及伺服器預設金鑰儲存庫中的私密金鑰,來簽署 JWT。這項配置會假設將預設金鑰儲存庫配置給伺服器,該預設金鑰儲存庫含有單一私密金鑰,且該私密金鑰可用於簽署。如果您在 keyStoreRef 屬性上指定不同的金鑰儲存庫,則會使用指定金鑰儲存庫中的私密金鑰。如果沒有配置 keyAlias 屬性,且金鑰儲存庫只包含一個私密金鑰,則會在簽章中使用該私密金鑰。

    您可以重新配置這個預設 jwtBuilder 元素,或是建立一或多個其他的 jwtBuilder 元素。每一個 jwtBuilder 元素必須有一個指定成 id 屬性,且可在 URL 中安全傳輸的唯一字串。如果遺漏該 ID,就不會處理 jwtBuilder

    如果 JWT 記號是用 RS256 演算法來簽署,您可以設定 jwkEnabled="true",將 JWT 建置器配置成使用「JSON Web 金鑰 (JWK)」來簽署 JWT 記號。當啟用 JWK 時,JWT 建置器會動態產生金鑰組,並以私密金鑰來簽署 JWT 記號。如果要驗證簽章,JWT 消費者可以從 JWK API 擷取金鑰,其格式如下:
    https://<host_name>:<ssl_port>/jwt/ibm/api/<jwtBuilder_configuration_id>/jwk
  5. 在您的應用程式中實作 com.ibm.websphere.security.jwt.JwtBuildercom.ibm.websphere.security.jwt.JwtToken API,以便以程式設計方式來建置 JWT 記號。

    如需相關資訊,請參閱 JSON Web 記號 Java 說明文件

    1. 建立 JwtBuilder 物件。
      如果您沒有指定配置 ID,則物件會關聯於預設 jwtBuilder 配置。
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create();
      如果您有指定配置 ID,物件會關聯於具有指定 ID 的 jwtBuilder 配置。
      com.ibm.websphere.security.jwt.JwtBuilder jwtBuilder = JwtBuilder.create("jwtBuilder_configuration_id");
    2. 修改記號中的聲明。
      • 新增或更新聲明:jwtBuilder.claim("claim_name", "claim_value");
        jwtBuilder.claim("role", "monitor");
      • 刪除聲明:jwtBuilder.remove("claim_name");
        jwtBuilder.remove("role");
      • 從「Liberty 聯合使用者登錄」提取聲明:jwtBuilder.fetch("attribute_name");

        這項提取呼叫是告訴 JwtBuilder 物件搜尋「聯合使用者登錄」,以找出 JWT sub 聲明所識別的使用者名稱。JwtBuilder 物件會提取指定屬性的值,並根據該屬性來建立新聲明。新聲明的名稱會設為該屬性名稱,新聲明的值會設為該屬性值。

      • 複製現有 JWT 或 JSON 物件中的聲明:jwtBuilder.claimFrom(JSON_or_JWT, "claim_name");
    3. 修改所配置的簽章演算法和簽署金鑰。
      jwtBuilder.signWith("new_algorithm", new_key);
    4. 使用 com.ibm.websphere.security.jwt.JwtToken API,來建置記號。
      JwtToken jwtToken = jwtBuilder.buildJwt();
      String jwtTokenString = jwtToken.compact();

「JSON Web 記號 API」範例

下列範例是建立新的 JWT。
JwtBuilder jwtBuilder = JwtBuilder.create();
jwtBuilder.subject("tom@op.com").claim(Claims.AUDIENCE, "https://acme.com/rs").claim("iss","https://sso.com/ibm/op" ).claim("scope", "impersonator monitor").claim("uid", "hasys123haksiqws");
JwtToken goToken = jwtBuilder.buildJwt();
產生的 JWT 是以伺服器的預設私密金鑰來簽署,並且包含下列聲明。
{
"aud": "https://acme.com/rs",
"iss": "https://sso.com/ibm/op",
"iat": 1388440863, "exp": 1388444763,
"uid": "hasys123haksiqws",
"sub": "tom@op.com",
"scope": "impersonator monitor"
}
下列範例是從另一個 JWT goToken,來建置 newToken JWT。
JwtToken newToken = JwtBuilder.create().claim(Claims.AUDIENCE, "https://acme.com/rs").claimFrom(goToken, "sub").claim(goToken, "uid").claim(goToken, "scope").buildJwt();

指示主題類型的圖示 作業主題

檔名:twlp_sec_build_jwt.html