[16.0.0.4 and later]

Liberty での JSON Web Token の作成

サーバー構成に 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 の資料を参照してください。

手順

  1. [18.0.0.1 and later]JWT トークン生成エンドポイントか ら JWT トークンを取得します。
    1. jwt-1.0 フィーチャーのエンドポイントでプログラミングせずにトークンを取得します。
    2. 資格情報を要求に含めなかった場合は、https://<host>:<port>/jwt/api/ibm/<configId>/token のエンドポイント にアクセスするため、資格情報で認証します。 認証が成功すると、MP-JWT 形式のトークン が JSON 形式で返されます。トークンには、サーバーのユーザー・レジストリーに登録 されているユーザーとそのユーザーのグループが含まれます。
    3. 発行者や有効期限などのその他のトークン属性を、 server.xml ファイルにある JWTBuilder エレメントの属性から <configId> ID を使用して設定します。
    4. server.xml ファイルで JWTBuilder エレメントを定義しない場合 、<configId> ID として defaultJWT を使用します。 使用可能な JWT Builder 構成属性を jwtBuilder - JWT Builder (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 属性に構成します。
    • 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
  5. com.ibm.websphere.security.jwt.JwtBuilder API と com.ibm.websphere.security.jwt.JwtToken API をアプリケーション内に実装して、JWT トークンをプログラマチックに作成します。

    詳しくは、JSON Web Token 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 Federated User Registry からクレームをフェッチします: jwtBuilder.fetch("attribute_name");

        このフェッチ呼び出しは、JwtBuilder オブジェクトに対し、JWT の sub クレームによって識別されるユーザー名を Federated User Registry で検索するように指示します。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 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();

トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_sec_build_jwt.html