[16.0.0.3 以降]

OpenID Connect の JSON Web Token 認証の構成

信頼できる認証プロキシー、信頼できるサービス・クライアント、または OAuth 許可サーバーからの認証トークンとして JSON Web Token (JWT) トークンを受け入れるように Liberty サーバーを構成することができます。

このタスクについて

JWT トークンを認証トークンとして受け入れるように Liberty サーバーを構成するには、openidConnectClient-1.0 フィーチャーを有効にし、inboundPropagation="required" を設定し、トラストストアと SSL を構成します。オプションで、ユーザー・レジストリー、認証フィルター、およびクレームとサブジェクトのマッピングなどの追加の JWT 構成を指定することができます。JWT を認証トークンとして使用するための構成は、Liberty での OpenID Connect クライアントの構成に類似しています。

JWT トークンを所有する信頼できるパーティーは、そのトークンを使用して、Liberty 内の関連したリソースにアクセスすることができます。Liberty リソース・サーバーは、JWT トークンを検証し、JWT トークンから認証済みサブジェクトを作成します。認証トークンとして受け入れられるためには、JWT トークンは、isssub、および exp の各クレームを含んでおり、RS256 または HS256 のアルゴリズムによって署名されている必要があります。暗号化された JWT はサポートされていません。以下の例は、デコードされた JWT ペイロードを示しています。
{
	"iss":"https://idp.acme.com:8020/jwt",
	"sub":"marissa@acme.com",
	"exp":1385066178,
	"aud":"https://resource.acme.com/services",
	"iat":1385062578,
	“groupIds”: [
	    “group1”, “group2”
	 ]  
}

手順

  1. server.xml ファイルに openidConnectClient-1.0 の Liberty フィーチャーと他の必要なフィーチャーを追加します。 openidConnectClient-1.0 フィーチャーには、最小で ssl-1.0 フィーチャーが必要です。server.xml ファイルの featureManager エレメントに次のエレメント宣言を追加します。
    <feature>openidConnectClient-1.0</feature> 	
    <feature>ssl-1.0</feature>
  2. openidConnectClient エレメントを構成し、inboundPropagation="required" を設定します。その他の openidConnectClient 属性については、OpenID Connect クライアント (openidConnectClient)を参照してください。

    以下のサンプル構成では、JWT トークン発行者が JSON Web Key (JWK) をサポートしており、RS256 アルゴリズムによって署名されていることが想定されています。

    <openidConnectClient id="RS" inboundPropagation="required"		
      jwkEndpointUrl="https://acme.com/jwtserver/jwk" signatureAlgorithm="RS256"
      issuerIdentifier="https://idp.acme.com:8020/jwt" >		
    </openidConnectClient>
  3. Liberty サーバーが JWK エンドポイントへの SSL 接続を実行できるように、JWK エンドポイント証明書を組み込むようにトラストストアを構成します。トラストストアは、server.xml ファイル内の keyStore エレメントに構成されます。 このトラストストアを参照するように SSL を構成した後は、その SSL 構成をサーバーのデフォルト SSL 構成として設定するか、openidConnectClient エレメントの sslRef 属性にトラストストア ID を指定することができます。

    JWT 発行者が JWK をサポートしておらず、JWT が代わりに X.509 証明書によって署名されている場合は、発行者の X.509 証明書をトラストストアにインポートします。openidConnectClient エレメントで、trustStoreRef 属性にトラストストア ID を指定し、trustAliasName 属性で証明書を参照します。

    JWT が、HMAC-SHA256 アルゴリズムを用いる共有秘密鍵を使用して署名されている場合は、sharedKey 属性または clientSecret 属性にその共有秘密鍵を定義します。

    トラストストアまたは鍵ストアについて詳しくは、Liberty の SSL 通信の使用可能化を参照してください。

  4. openidConnectClient エレメントの issuerIdentifier 属性が JWT 発行者の iss クレームに一致するように構成します。

    例えば、JWT トークンに "iss":"https://idp.acme.com:8020/jwt" が含まれている場合、issuerIdentifier="https://idp.acme.com:8020/jwt" と設定します。

  5. オプション: ユーザー・レジストリーを構成します。 デフォルトで、JWT をユーザーにマップせずに、検証済み JWT クレームを使用して呼び出し元の認証済みサブジェクトを直接作成するため、ユーザー・レジストリーは必要ありません。

    ただし、openidConnectClient エレメントの mapIdentityToRegistryUser 属性が true に設定されている場合、認証および許可が成功するためには、該当する ID のユーザー・エントリーが許可サーバーから返される必要があります。ユーザー・レジストリーの構成について詳しくは、Liberty のユーザー・レジストリーの構成を参照してください。

  6. オプション: 認証フィルターで説明されているように認証フィルターを構成します。

    認証フィルターを構成する場合は、openidConnectClient エレメントの authFilterRef 属性でその認証フィルターを参照します。

    openidConnectClient エレメントが authFilterRef 属性を使用して構成されていない場合、非認証要求試行はこの openidConnectClient エレメントによって認証されます。

  7. オプション: 複数の openidConnectClient エレメントと複数の認証フィルターを構成して、Liberty リソース・サーバーが複数の JWT 発行者または認証プロキシー・サーバーで機能するように構成します。

    openidConnectClient エレメントは、1 つの JWT 発行者または認証プロキシーとの 1 つの信頼関係を定義し、1 つの認証フィルターを参照します。

  8. オプション: JWT クレームを認証サブジェクトにマップするためのルールを定義します。
    Liberty リソース・サーバーは JWT クレームを使用して認証サブジェクトを作成し、ユーザーは、以下の openidConnectClient エレメント属性で JWT クレームをサブジェクトにマップする方法を定義できます。
    • userIdentifier
    • userUniqueIdentifier
    • groupIdentifier
    • realmName
    • realmIdentifier
    realmNamerealmIdentifier の両方が構成されている場合は、realmName が優先され、realmIdentifier は無視されます。
    クレームとサブジェクトのマッピングを定義しない場合、以下のデフォルト・マッピング・ルールが適用されます。
    • サブジェクト (sub) クレームは、ユーザーのプリンシパル名および固有セキュリティー名として使用される。
    • 発行者 (iss) クレームは、デフォルト・レルムであり、サブジェクト・レルムとして使用される。realmName クレームが JWT トークンに含まれている場合は、iss クレームではなく realmName クレームがサブジェクト・レルムとして使用される。
  9. オプション: シングル・サインオン Cookie を構成します。 Liberty サーバーは、各要求が有効な JWT トークンを提供することを予期しており、認証用にシングル・サインオン Cookie を作成または使用しません。シングル・サインオン Cookie を作成するには、openidConnectClient エレメントに authnSessionDisabled="false" を設定します。
  10. オプション: JWT トークンを受け取るように Liberty サーバーを構成します。Web クライアントは、次のいずれかのメソッドを使用して、Liberty リソース・サーバーへのリソース要求で JWT トークンを送信します。JWT トークンが Authorization フィールドまたはフォーム・エンコードされたボディ・パラメーターで送信された場合、追加のサーバー構成は必要ありません。
    重要: クライアントは、トークンを送信するための各要求で複数のメソッドを使用してはいけません。headerName 属性が構成されている場合、Authorization ヘッダー・フィールドまたはフォーム・エンコードされたボディ・パラメーターで送信されるトークンは無視されます。headerName 属性が構成されていない場合は、Authorization ヘッダーが最初に検索され、その後に access_token パラメーターが検索されます。
    • Authorization 要求ヘッダー・フィールドでトークンを送信する。
      GET /resource HTTP/1.1
      Host: server.example.com
      Authorization: Bearer mF_9.B5f-4.1JqM
    • フォーム・エンコードされたボディ・パラメーターとして要求エンティティー本体でトークンを送信する。
      POST /resource HTTP/1.1
      Host: server.example.com
      Content-Type: application/x-www-form-urlencoded
      access_token=mF_9.B5f-4.1JqM
    • Liberty に信頼できるヘッダー名を構成して、カスタマイズされた要求ヘッダーでトークンを送信する。

      信頼できるヘッダー名を構成するには、openidConnectClient エレメントに headerName="<myJwtHeaderName>" を設定します。例えば、headerName="jwt" を設定すると、次の例に示すように、jwt ヘッダー・フィールドでトークンを送信できます。
      GET /resource HTTP/1.1
      Host: server.example.com
      jwt: mF_9.B5f-4.1JqM
  11. JWT オーディエンスを構成します。 信頼できるオーディエンスのリストを定義するには、openidConnectClient エレメントに audiences 属性を構成します。
    有効な JWT トークンは、次のいずれかの条件を満たしている必要があります。
    • audiences 属性が構成されている場合、オーディエンス (aud) クレーム値は、構成されているいずれかのオーディエンスでなければなりません。オーディエンス・チェックを無視するには、audiencesALL_AUDIENCES に設定します。
    • audiences 属性は構成されていないが、JWT トークンに、有効な URL である aud クレームが含まれている場合、リソースのサービス URL には、aud 値が接頭部として付加されている必要があります。
      例えば、以下のオーディエンスは、リソースの URL が aud クレーム値で開始されているため有効です。
      • オーディエンス・クレーム: "aud":"https://<server>:<port>/something"
      • リソース URL: https://<server>:<port>/something/specific
      以下のオーディエンスは、リソース URL が aud クレーム値で開始されていないため無効です。
      • オーディエンス・クレーム: "aud":"https://<server>:<port>/something/specific"
      • リソース URL: https://<server>:<port>/something
  12. オプション: com.ibm.wsspi.security.oauth.UserCredentialResolver サービス・プログラミング・インターフェース (SPI) を実装して、プログラマチックに JWT トークンをサブジェクトにマップします。

    このインターフェースについて詳しくは、『プログラミング・インターフェース (API および SPI)』で、または、製品と一緒に ${wlp.install.dir}/dev/spi/ibm/ ディレクトリー内に提供される Java 文書で、com.ibm.wsspi.security.oauth.UserCredentialResolver SPI についての説明を参照してください。

タスクの結果

JWT トークンを認証トークンとして受け入れるように Liberty サーバーを構成するのに必要な最小構成が作成されました。

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



タイム・スタンプ・アイコン 最終更新: Monday, 5 December 2016
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-libcore-mp&topic=twlp_sec_config_oidc_jwt
ファイル名: twlp_sec_config_oidc_jwt.html