アプリケーション開発ガイド（共通）: WebOTX Developer Manual

WebOTX Manual V11.1 (第6版)

目次を表示

14.5. MicroProfile JWT Authentication

14.5.1. 概要

MicroProfile JWT Authentication は、OpenID Provider から返却されたトークンの復号化等の変換を行う機能を提供します。

MicroProfile JWT Authentication の提供機能

14.5.2. 設定情報

MicroProfile JWT Authentication の設定項目は、[ リファレンス > 設定 > マイクロサービスアプリケーション > MicroProfile JWT Authentication ] を参照してください。

14.5.3. 提供機能

MicroProfile JWT Authentication は、次のアノテーションを提供します。各アノテーションの詳細は MicroProfile JWT Auth API 1.2 API を参照してください。

名称	説明	アノテーション名
LoginConfig	認証方法を指定します。	@LoginConfig
Claim	JWT のクレームを指定します。	@Claim

14.5.3.1. LoginConfig

認証方法を指定します。また、web.xml の <login-config> でも同等の認証方法を指定することができます。
@LoginConfig と、web.xml の両方が指定されていた場合は、web.xml での指定が優先されます。

パラメータ	説明	既定値
authMethod	認証方法に "MP-JWT" を指定します。	無し
realmName	レルム名を指定します。	""

14.5.3.2. Claim

JWT のクレームを指定します。

パラメータ	説明	既定値
value	クレーム名を指定します。	""
standard	org.eclipse.microprofile.jwt.Claims の列挙型で定義されている値を使って、クレーム名を指定します。 standard パラメータに指定可能な、主なクレームについては、下記を参照してください。指定可能なすべてのクレームは、org.eclipse.microprofile.jwt.Claims を参照してください。	Claims.UNKNOWN

standard パラメータに指定できる主なクレーム
値	内容	備考
iss	Issuer クレーム。JWT の発行者情報	RFC 7519, Section 4.1.1
sub	Subject クレーム。JWT の主語となる主体の識別子	RFC 7519, Section 4.1.2
exp	Expiration Time クレーム。JWT の有効期限	RFC 7519, Section 4.1.4
iat	Issued At クレーム。JWT を発行した時刻	RFC 7519, Section 4.1.6
jti	JWT ID クレーム。JWT のための一意な識別子	RFC 7519, Section 4.1.7
upn	ユーザープリンシパル名	MicroProfile JWT Authentication のカスタムクレーム
groups	グループ名	MicroProfile JWT Authentication のカスタムクレーム
raw_token	Authentication ヘッダの元のトークン文字列	MicroProfile JWT Authentication のカスタムクレーム

14.5.4. JWT 認証方法の指定

14.5.4.1. アノテーションでの指定

アノテーションを使用した JWT 認証方法の記述例を下記に示します。

@LoginConfig を用いて、JWT 認証方法を指定します。

@LoginConfig(authMethod = "MP-JWT", realmName = "JWTRealm")
@Path("/name_list")
@RequestScoped
public class CustomerResource {
        :

14.5.4.2. web.xml での指定

web.xml を使用した JWT 認証方法の記述例を下記に示します。

web.xmlの<login-config>内で、JWT認証方式を設定します。

<login-config>
    <auth-method>MP-JWT</auth-method>
    <realm-name>JWTRealm</realm-name>
</login-config>

Memo
@LoginConfig と web.xml の両方が指定されていた場合は、web.xml での指定が優先されます。

14.5.5. クレームの情報取得

@Claim や org.eclipse.microprofile.jwt.JsonWebToken を用いて、受信した HTTP Authorization:Bearer ヘッダからクレームを取得します。

定義や、取得イメージは次の通りです。

@Inject
private JsonWebToken jwt;

// Raw types
@Inject
@Claim(standard = Claims.iat)
private Long issuedAt;
@Inject
@Claim("customerId")
private String customerId;

// ClaimValue wrappers
@Inject
@Claim(standard = Claims.groups)
private ClaimValue<Set<String>> groups;

public Customer getCustomerList(@PathParam("id") String id) {
            :
    String userName = jwt.getClaim("preferred_username");

    if (issuedAt > System.currentTimeMillis() ||
        (groups != null) && !groups.getValue().contains("admin") ||
        !id.equals(userName)) {
            :
        throw new WebApplicationException(403);
    }
            :
}

14.5.6. OpenIDサーバ公開鍵の設定

JWTの暗号化と復号化で利用する、OpenIDサーバの公開鍵を設定します。mp.jwt.verify.publickey あるいは mp.jwt.verify.publickey.location プロパティでの指定と、アプリケーション内の META-INF/MP-JWT-SIGNER ファイルで指定する方法があります。

Memo
後述するサンプルプロジェクトでは、評価用の公開鍵を使用しています。
実際には、OpenIDサーバから取得した公開鍵をご利用ください。

mp.jwt.verify.publickey プロパティに公開鍵を設定します。

META-INF/microprofile-config.properties ファイルで指定する場合の設定イメージは、次の通りです。

mp.jwt.verify.publickey=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlivFI8qB4D0y2jy0CfEqFyy46R0o7S8TKpsx5xbHKoU1VWg6QkQm+ntyIv1p4kE1sPEQO73+HY8+Bzs75XwRTYL1BmR1w8J5hmjVWjc6R2BTBGAYRPFRhor3kpM6ni2SPmNNhurEAHw7TaqszP5eUF/F9+KEBWkwVta+PZ37bwqSE4sCb1soZFrVz/UT/LF4tYpuVYt3YbqToZ3pZOZ9AX2o1GCG3xwOjkc4x0W7ezbQZdC9iftPxVHR8irOijJRRjcPDtA6vPKpzLl6CyYnsIYPd99ltwxTHjr3npfv/3Lw50bAkbT4HeLFxTx4flEoZLKO/g0bAoV2uqBhkA9xnQIDAQAB

mp.jwt.verify.publickey.location プロパティに公開鍵の位置を指定します。
https://WebOTX/publicKey.jwk で、公開鍵が公開されている場合の設定イメージは、次の通りです。
```
mp.jwt.verify.publickey.location=https://WebOTX/publicKey.jwk
```
Memo
本プロパティで、https:// スキームを利用する場合は、事前に、接続先となるサーバのサーバ証明書を、WebOTX のトラストストアに登録しておく必要があります。詳細は、[ リファレンス > 設定 > 共通SSL設定 ] を参照してください。

アプリケーションの META-INF/MP-JWT-SIGNER ファイルに公開鍵を設定します。

META-INF/MP-JWT-SIGNER ファイルの設定イメージは、次の通りです。

14.5.7. OpenIDサーバ発行者情報の設定

OpenIDサーバのセキュリティ発行者情報を設定します。mp.jwt.verify.issuer プロパティでの指定と、アプリケーション内の META-INF/MP-JWT-ISSUER ファイルで指定する方法があります。

mp.jwt.verify.issuer プロパティに発行者情報を設定します。
META-INF/microprofile-config.properties ファイルで指定する場合の設定イメージは、次の通りです。
```
mp.jwt.verify.issuer=https://server.example.com
```
META-INF/MP-JWT-ISSUERファイルに発行者情報を設定します。
設定イメージを下記に示します。
```
https://server.example.com
```

14.5.8. サンプルの実行

ここでは、MicroProfile JWT のサンプルアプリケーションを実行する手順について、説明します。

サンプルプロジェクト Jaxrs20SampleJSON_with_JWT.zip

(1) WebOTX Developer へのインポート
サンプルプロジェクトの zip ファイルを展開して、WebOTX Developer にインポートしてください。

(2) JWT 認証を利用する JAX-RS アプリケーションの作成
@LoginConfig アノテーションで、JWT 認証を指定したクラスを作成します。本クラスを含め、sample パッケージの全体は、上述のサンプルプロジェクトを確認してください。

src/sample/CustomerResource.java

package sample;

import java.util.Map;
import java.util.Set;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.WebApplicationException;
import javax.ws.rs.core.MediaType;

import sample.resource.Customer;
import sample.util.Util;

import javax.enterprise.context.RequestScoped;

import javax.inject.Inject;

import org.eclipse.microprofile.auth.LoginConfig;
import org.eclipse.microprofile.jwt.Claim;
import org.eclipse.microprofile.jwt.Claims;
import org.eclipse.microprofile.jwt.ClaimValue;
import org.eclipse.microprofile.jwt.JsonWebToken;


@LoginConfig(authMethod = "MP-JWT", realmName = "JWTRealm")
@Path("/name_list")
@RequestScoped
public class CustomerResource {

    @Inject
    private JsonWebToken jwt;

    // Raw types
    @Inject
    @Claim(standard = Claims.iat)
    private Long issuedAt;
    @Inject
    @Claim("customerId")
    private String customerId;

    // ClaimValue wrappers
    @Inject
    @Claim(standard = Claims.groups)
    private ClaimValue<Set<String>> groups;

    @Path("{id}")
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Customer getCustomerList(@PathParam("id") String id) {
        // load data
        Map<String, Customer> map = Util.loadData("/sample/data/customerlist.txt");
        Customer customer = map.get(customerId);

        String userName = jwt.getClaim("preferred_username");

        if (issuedAt > System.currentTimeMillis() ||
            (groups != null) && !groups.getValue().contains("admin") ||
            !id.equals(userName)) {
            System.out.println("customerId [" + customerId  +"] Forbidden ----------\n"
                + "  issuedAt : " + issuedAt + "\n"
                + "  groups : " + groups + "\n"
                + "  preferred_username : " + userName);
            throw new WebApplicationException(403);
        }

        return customer;
    }
}

(3) クライアントアプリケーションの作成
JAX-RS アプリケーションへのリクエストを送信するクライアントアプリケーションを作成します。

Memo
サンプルでは Token1.json に設定したトークン情報からJWTを自己生成し、HTTP Authorization:Bearer ヘッダに付与しています。
実際には OpenID サーバから取得した JWT をご利用ください。

client/src/TestClient.java

import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.HttpHeaders;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.eclipse.microprofile.jwt.tck.util.TokenUtils;

public class TestClient {

    public static void main(String[] args) {

        if (args.length == 0) {
            System.out.println("usage: java TestClient <request url>");
            System.out.println("exit.");
            return;
        }

        try {
            String token = TokenUtils.generateTokenString("/Token1.json");

            String uri = args[0];

            WebTarget target = ClientBuilder.newClient().target(uri);
            Response response = target.request(MediaType.APPLICATION_JSON).header(HttpHeaders.AUTHORIZATION, "Bearer " + token).get();

            String reply = response.readEntity(String.class);
            System.out.println(reply);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

(4) プロジェクトのビルド
WebOTX Developer のメニュー「プロジェクト」で「自動的にビルド」がチェックされていない場合は、「プロジェクトのビルド」を選択し、ビルドを行います。

(5) warファイルのエクスポート
プロジェクトを右クリックして、「エクスポート」－「WAR ファイル」を選択します。「Destination」で出力先のパスを指定し、「終了」ボタンをクリックします。

(6) JAX-RS アプリケーションの配備
対象の環境に合わせて、アプリケーションを配備します。

コンテナ環境の場合は、[ 構築・運用 > コンテナ型仮想化 ] を参考に、本サンプルアプリケーションを含めたコンテナイメージを作成して、コンテナを起動してください。

コンテナ環境でない場合は、[ 配備 > アプリケーション配備 > 配備・再配備・置換 > 配備・再配備 ] を参考に、配備してください。
例) エージェントプロセス上に配備する場合

otxadmin> deploy Jaxrs20SampleJSON_with_JWT.war

(7) クライアントアプリケーションの実行
次の Java コマンドを実行してください。接続先ホスト名、HTTPポート番号は、環境に合わせて変更してください。

java -Dsun.net.http.allowRestrictedHeaders=true TestClient http://localhost:8080/Jaxrs20SampleJSON-with-JWT/name_list/0001

Java コマンド実行時、クラスパスには、次のものを設定してください。

  {サンプルプロジェクト展開ディレクトリ}/client/classes
  {サンプルプロジェクト展開ディレクトリ}/client/lib/microprofile-jwt-auth-tck-1.1.1.jar
  {サンプルプロジェクト展開ディレクトリ}/client/lib/nimbus-jose-jwt-4.23.jar
  {サンプルプロジェクト展開ディレクトリ}/client/lib/json-smart-1.3.1.jar
  ${AS_INSTALL}/lib/gf-client.jar
  ${AS_INSTALL}/modules/jakarta.ws.rs-api.jar
  ${AS_INSTALL}/modules/microprofile-jwt-auth-api.jar
  ${AS_INSTALL}/modules/jersey-client.jar
  ${AS_INSTALL}/modules/jersey-common.jar
  ${AS_INSTALL}/modules/jersey-hk2.jar

Memo
WebOTX Developer を使って実行する場合は、メニューの「実行」－「実行構成」で表示される画面で、「Java アプリケーション」－「MicroProflie_JWT_Client」を選択して、「実行」ボタンクリックにより、実行してください。
なお、この場合の接続先ホスト名、ポート番号は、「実行構成」－「MicroProflie_JWT_Client」の「引数」タブの「プログラムの引数」にて変更可能です。

クライアントアプリケーションを実行すると、配備されたサンプルアプリケーションに、JWT トークンが設定されたリクエストが送信され、下記のレスポンスコンテンツが返却されます。

{"姓":"田中","名":"太郎"}