[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. server.xml 檔中,新增 jwt-1.0 特性。
    <featureManager>
        <feature>jwt-1.0</feature>
        ...
    </featureManager>
  2. 修改 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
  3. 在您的應用程式中實作 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();

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



「時間戳記」圖示 前次更新: 2016 年 11 月 30 日
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twlp_sec_build_jwt
檔名:twlp_sec_build_jwt.html