[17.0.0.3 and later]

MicroProfile JSON Web トークンの構成

MicroProfile JSON Web トークンを認証トークンとして受け入れるように Liberty サーバーを構成できます。

始める前に

mpJwt-1.0 フィーチャーを使用するため、Java™ Platform, Standard Edition (Java SE) 8 以上をインストールします。

このタスクについて

MicroProfile 1.2 は、以下の 3 つの部分を含んでいる相互運用可能な JSON Web Token (MP-JWT) 標準を定義したものです。
  • トークンのフォーマットおよびクレーム
  • org.eclipse.microprofile.jwt.JsonWebToken インターフェース。 これは、java.security.Principal インターフェースの拡張であり、このクレーム集合を get style アクセサーを介して使用可能にします。
  • JSON Web トークンおよびクレームから、さまざまな Java EE コンテナー・アプリケーション・プログラミング・インターフェース (API) へのマッピング

MP-JWT 仕様および API について詳しくは、JWT RBAC for MicroProfile を参照してください。

MP-JWT トークンを所有する信頼できるパーティーは、許可ヘッダーを介してトークンを送信することで、そのトークンを使用して Liberty 内の関連したリソースにアクセスできます。次の例に示すように、トークン・ワイヤー・フォーマットは RFC 6750 仕様 (「The OAuth 2.0 Authorization Framework: Bearer Token Usage」) に準拠していなければなりません。

GET /resource/1 HTTP/1.1
Host: example.com
Authorization: Bearer <MP-JWT token>
Liberty リソース・サーバーは、MP-JWT トークンを検証し、認証済み JSON Web トークンを作成し、JSON Web トークンおよびトークン・クレームを CDI 注入または JAX-RS セキュリティー・コンテキストを介して使用可能にします。JWT トークンは、MP-JWT トークンとして受け入れられるためには、クレームのリストを含んでいる必要があります。以下は、MP-JWT トークンの例です。
{
    "typ": "JWT",
    "alg": "RS256",
    "kid": "abc-1234567890"
}
{
       "iss": "https://server.example.com",
       "aud": "s6BhdRkqt3",
       "jti": "a-123",
       "exp": 1311281970,
       "iat": 1311280970,
       "sub": "24400320",
       "upn": "jdoe@server.example.com",
       "groups": ["red-group", "green-group", "admin-group", "admin"],
}

手順

  1. server.xml ファイルに mpJwt-1.0 フィーチャーと他の必要なフィーチャーを追加します。 mpJwt-1.0 フィーチャーは、最低限、AppSecurity-2.0 フィーチャーおよび jaxrs-2.0 フィーチャーを必要とし、しばしば Contexts and Dependency Injection (CDI) フィーチャーと共に使用されます。
    <featureManager>
        <feature>mpJwt-1.0</feature>
        <feature>appSecurity-2.0</feature>
        <feature>jaxrs-2.0</feature>
        <feature>cdi-1.2</feature>
        ...
    </featureManager>
  2. mpJwt エレメントを構成します。
    1. issuer 属性を追加します。Java Web トークン (JWT) 内の iss クレームに一致する、この属性の値を入力します。
    2. JWT に aud クレームが含まれている場合は、audiences 属性を追加します。JWT 内のその aud クレームの値 1 つを含むこの属性の値を入力します。
    3. jwksUri 属性を追加します。JSON Web キー (JWK) の URL に一致する、この属性の値を入力します。 以下のコードは、JWK が指定された典型的な mpJwt 構成エレメントを示しています。
      <mpJwt 
           id="myMpJwt"
           jwksUri="https://example.com/api/jwk"      issuer="https://example.com/api/v1"
           audiences="conferenceService">
      </mpJwt>
    4. Secure Sockets Layer (SSL) 構成の truststore ファイルに JWT 署名検証キーを追加する場合、keyName 属性を追加します。 keyName 属性は、truststore ファイル内の鍵別名を指定します。 以下のコードで、サンプルの mpJwt 構成を示します。
      <mpJwt 
           keyName="mpJwtValidationKey"      issuer="https://example.com/api/v1"
           audiences ="conferenceService">
      </mpJwt>
  3. Liberty サーバーが JWK エンドポイントへの SSL 接続を実行できるように、JWK エンドポイント証明書を組み込むように truststore ファイルを構成します。
    1. server.xml ファイル内の keystore エレメントに truststore を構成します。
    2. この truststore ファイルを参照するように SSL を構成します。
    3. SSL 構成をサーバーのデフォルト SSL 構成として設定するか、または、mpJwt エレメントの sslRef 属性に truststore ID を指定します。
    4. JWT 発行者が JWK をサポートしておらず、JWT が X.509 証明書によって署名される場合は、発行者からの X.509 証明書を SSL 構成内の truststore ファイルにインポートします。 詳しくは、Liberty の SSL 通信の使用可能化を参照してください。
  4. オプション: MP-JWT フォーマットではない JWT の場合に JWT クレームを認証サブジェクトにマップするためのルールを定義します。 デフォルトでは、 プログラムは、セキュリティー・ロールのマッピングのために、upn クレームをユーザーのプリンシパル名および固有セキュリティー名として使用し、groups クレームをグループ名として使用します。デフォルトのマッピングを変更するには、userNameAttribute 属性を使用して、ユーザー・プリンシパル用のクレームを選択し、groupAttribute 属性を使用して、グループ名用のクレームを選択します。
  5. オプション: JAX-RS アプリケーションを使用して、API javax.ws.rs.core.SecurityContext.getUserPrincipal() を呼び出すことによって JsonWebToken getter にアクセスします。 次の例では、ユーザー・プリンシパルが org.eclipse.microprofile.jwt.JsonWebToken API のインスタンスとしてキャストされていて、アプリケーションは JsonWebToken getter を介してすべてのクレームにアクセスできます。
    @GET
    @Path("/getGroups")
    public Set<String> getGroups(@Context SecurityContext sec) {
           Set<String> groups = null;
           Principal user = sec.getUserPrincipal();
           if (user instanceof JsonWebToken) {
                    JsonWebToken jwt = (JsonWebToken) user;
                    groups= = jwt.getGroups();
           }
           return groups;
    }
  6. オプション: 以下の例のように、JAX-RS アプリケーションを使用して、Raw TypeClaimValuejavax.inject.Provider、および JSON-P タイプを通して、org.eclipse.microprofile.jwt.JsonWebToken API を注入します。
    @RequestScoped
    public class JwtEndpoint {
           @Inject
           private JsonWebToken jwtPrincipal;
           @GET
           @Path("/getInjectedPrincipal")
           public String getInjectedJWT() {
              return  this.jwtPrincipal.getName();
           }
    }
  7. オプション: プログラムがプログラマチック・セキュリティーを実行していて、org.eclipse.microprofile.jwt.JsonWebToken API をサブジェクトから取得できる場合、com.ibm.websphere.security.auth.WSSubject.getCallerPrincipal() API を使用します。 現行のセキュリティー・コンテキストでは、サブジェクトには 2 つの java.security.Principal プリンシパルが含まれています。 1 つのプリンシパルが JSON Web トークンです。
  8. オプション: [17.0.0.4 and later]アノテーションおよび JWT のグループ・クレームを使用して JAX-RS リソースを保護します。 @RolesAllowed アノテーションで使用されるセキュリティ ー・ロール名は、JWT のグループ・クレーム内のグループ名にマップされます。 ロール名とグループ名が同じ場合、 application-bnd エレメントのロール・マッピング を省略することができます。ただし、JWT がグループ情報を含む MP-JWT の場合は、 application-bnd エレメントにマップして、ロールとグルー プの関連付けを宣言します。詳しくは、Securing JAX-RS resources using annotationsアクセス ID と許可、およびロール・マッピング・バインディングが提供されていない場合のアプリケーションの許可を参照してください。
  9. オプション: [17.0.0.4 and later]構成済みの Liberty ユーザー・レジストリーに照らして JWT からのユーザー・プリンシパル名を検査するように Liberty を構成します。

    デフォルトでは、本プログラムは、セキュリティー・サブジェクトを、ユーザー・レジストリーを必要とせずに、検証された JWT から直接作成します。この動作を変更するには、 server.xml ファイル内で mapToUserRegistry="true" 構成属性を追加します。本プログラムは、構成されたユーザー・レジストリーに照らしてプリンシパル名を検索し、ユーザー・レジストリーからのユーザー属性に基づいてセキュリティー・サブジェクトを作成します。

  10. オプション: [17.0.0.4 and later]ログイン・メソッド名が MP-JWT であるアプリケーションにのみ mpJwt-1.0 フィーチャーを適用するように Liberty を構成します。
    デフォルトでは、mpJwt-1.0 フィーチャーが構成されている場合、すべての許可された要求では HTTP ヘッダー内に有効な JWT が含まれている必要があります。 このデフォルト動作を変更して、一部のアプリケーションでのみ JWT 認証ト ークンが必要であるようにするには、server.xml ファイル内の <mpJwt> エレメントに ignoreApplicationAuthMethod="false" 構成属 性を追加します。次に、次の 2 つの方法のどちらかで、アプリケーションを構成します。
    • アプリケーションが、認証方式として MP-JWT ログイン・メソッドが宣言された @LoginConfig アノテーションを含みます。

      例えば、@LoginConfig(authMethod = "MP-JWT", realmName = "MP-JWT") です。

    • アプリケーションの web.xml ファイルが、login-config エレメント内に MP-JWT 認証方式の宣言を含みます。

      例えば、<login-config> <auth-method>MP-JWT</auth-method> <realm-name>MP-JWT</realm-name></login-config> です。

  11. オプション: [17.0.0.4 and later]他の JAX-RS サービスを Liberty が呼び出したときに認証トークンとして MP-JWT を自動的に伝搬するように Liberty を構成します。

    Liberty が JAX-RS 2.0 クライアントとしても動作している場合、authnToken="mpjwt" ステートメントを <webTarget> 構成エレメントに追加します。そうすると、Liberty JAX-RS クライアントは、JAX-RS サービス呼び出しの許可ヘッダーとして JWT を自動的に追加します。例えば、 <webTarget uri="http://localhost:56789/protectedResourceWithMPJWT*" authnToken="mpjwt" /> エレメントを server.xml ファイルに追加すると、http://localhost:56789/protectedResourceWithMPJWT/ サービスが呼び出されるときに JWT トークンが許可ヘッダーに追加されます。


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

ファイル名: twlp_sec_json.html