您可以採程式設計方式來建置「JSON Web 記號 (JWT)」的記號,作法是在伺服器配置中配置
JWT 建置器元素,並在您的應用程式中實作
com.ibm.websphere.security.jwt.JwtBuilder 和
com.ibm.websphere.security.jwt.JwtToken API。
關於這項作業
如需 JWT API 的相關資訊,請參閱 JSON Web 記號 Java 說明文件,或產品之
${wlp.install.dir}/dev 目錄中所包含的 API 說明文件。
程序
從 JWT 記號產生端點取得 JWT 記號。 - 不需程式設計,即可利用 jwt-1.0 特性的端點來取得記號。
- 如果您沒有在要求中包含認證,則會鑑別您的認證,以存取位於
https://<host>:<port>/jwt/api/ibm/<configId>/token 的端點。 在鑑別成功之後,會以 JSON 形式傳回
MP-JWT 格式的記號。記號會包含使用者的使用者和群組,如同伺服器的使用者登錄中所記錄的一樣。
- 從 server.xml 檔中具有
<configId> ID 之 JWTBuilder 元素的屬性,來設定其他記號屬性,例如,發證者和有效期限。
- 如果您沒有在 server.xml 檔中定義 JWTBuilder 元素,請使用
defaultJWT 作為 <configId> ID。 可用的「JWT 建置器」配置屬性可在
jwtBuilder - JWT 建置器
(jwtBuilder) 中找到。
- 以程式設計方式,在 Liberty 中建置 JSON Web 記號。
- 在 server.xml 檔中,新增 jwt-1.0 特性。
<featureManager>
<feature>jwt-1.0</feature>
...
</featureManager>
- 修改 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
- 在您的應用程式中實作
com.ibm.websphere.security.jwt.JwtBuilder 和
com.ibm.websphere.security.jwt.JwtToken API,以便以程式設計方式來建置 JWT 記號。
如需相關資訊,請參閱 JSON Web 記號 Java 說明文件。
- 建立 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");
- 修改記號中的聲明。
- 新增或更新聲明: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");
- 修改所配置的簽章演算法和簽署金鑰。
jwtBuilder.signWith("new_algorithm", new_key);
- 使用 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();