サーバー構成に JWT ビルダー・エレメントを構成し、com.ibm.websphere.security.jwt.JwtBuilder API と com.ibm.websphere.security.jwt.JwtToken API をアプリケーション内で実装することにより、JSON Web Token (JWT) トークンをプログラマチックに作成することができます。
このタスクについて
JWT API について詳しくは、JSON Web Token の Java の資料、または製品の ${wlp.install.dir}/dev ディレクトリーに含まれている API の資料を参照してください。
手順
JWT トークン生成エンドポイントか
ら JWT トークンを取得します。 - jwt-1.0 フィーチャーのエンドポイントでプログラミングせずにトークンを取得します。
- 資格情報を要求に含めなかった場合は、https://<host>:<port>/jwt/api/ibm/<configId>/token のエンドポイント
にアクセスするため、資格情報で認証します。 認証が成功すると、MP-JWT 形式のトークン
が JSON 形式で返されます。トークンには、サーバーのユーザー・レジストリーに登録
されているユーザーとそのユーザーのグループが含まれます。
- 発行者や有効期限などのその他のトークン属性を、
server.xml ファイルにある JWTBuilder エレメントの属性から
<configId> ID を使用して設定します。
- server.xml ファイルで JWTBuilder エレメントを定義しない場合
、<configId> ID として
defaultJWT を使用します。 使用可能な JWT Builder
構成属性を jwtBuilder - JWT Builder
(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 属性に構成します。
- JWT は、RS256 アルゴリズムを使用してサーバーのデフォルト鍵ストア内の秘密鍵によって署名されます。この構成では、サーバー用のデフォルト鍵ストアが構成されており、そのデフォルト鍵ストアに単一の秘密鍵が含まれており、その秘密鍵を署名に使用できることが想定されています。keyStoreRef 属性に別の鍵ストアを指定すると、指定された鍵ストアの秘密鍵が使用されます。keyAlias 属性が構成されておらず、鍵ストアに含まれている秘密鍵が 1 つのみの場合は、その秘密鍵が署名に使用されます。
このデフォルトの jwtBuilder エレメントを再構成するか、1 つ以上の他の jwtBuilder エレメントを作成できます。各 jwtBuilder エレメントは、id 属性として指定される、固有で URL セーフのストリングを持っている必要があります。この ID がない場合、jwtBuilder は処理されません。
JWT トークンが RS256 アルゴリズムを使用して署名されている場合、
jwkEnabled="true" を設定することにより、JSON Web Key (JWK) を使用して JWT トークンに署名するように 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 API と com.ibm.websphere.security.jwt.JwtToken API をアプリケーション内に実装して、JWT トークンをプログラマチックに作成します。
詳しくは、JSON Web Token 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 Federated User Registry からクレームをフェッチします:
jwtBuilder.fetch("attribute_name");
このフェッチ呼び出しは、JwtBuilder オブジェクトに対し、JWT の sub クレームによって識別されるユーザー名を Federated User Registry で検索するように指示します。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 Token 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();