信頼できる認証プロキシー、信頼できるサービス・クライアント、または 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 トークンは、
iss、
sub、および
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”
]
}
- 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>
- openidConnectClient エレメントを構成し、inboundPropagation="required" を設定します。その他の openidConnectClient 属性について詳しくは、OpenID Connect Client を参照してください。
以下のサンプル構成では、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>
- 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 通信の使用可能化を参照してください。
- openidConnectClient エレメントの issuerIdentifier 属性が JWT 発行者の iss クレームに一致するように構成します。
例えば、JWT トークンに "iss":"https://idp.acme.com:8020/jwt" が含まれている場合、issuerIdentifier="https://idp.acme.com:8020/jwt" と設定します。
- オプション: ユーザー・レジストリーを構成します。 デフォルトで、JWT をユーザーにマップせずに、検証済み JWT クレームを使用して呼び出し元の認証済みサブジェクトを直接作成するため、ユーザー・レジストリーは必要ありません。
ただし、openidConnectClient エレメントの mapIdentityToRegistryUser 属性が true に設定されている場合、認証および許可が成功するためには、該当する ID のユーザー・エントリーが許可サーバーから返される必要があります。ユーザー・レジストリーの構成について詳しくは、Liberty のユーザー・レジストリーの構成を参照してください。
- オプション: 認証フィルターで説明されているように認証フィルターを構成します。
認証フィルターを構成する場合は、openidConnectClient エレメントの authFilterRef 属性でその認証フィルターを参照します。
openidConnectClient エレメントが authFilterRef 属性を使用して構成されていない場合、非認証要求試行はこの openidConnectClient エレメントによって認証されます。
- オプション: 複数の openidConnectClient エレメントと複数の認証フィルターを構成して、Liberty リソース・サーバーが複数の JWT 発行者または認証プロキシー・サーバーで機能するように構成します。
各 openidConnectClient エレメントは、1 つの JWT 発行者または認証プロキシーとの 1 つの信頼関係を定義し、1 つの認証フィルターを参照します。
- オプション: JWT クレームを認証サブジェクトにマップするためのルールを定義します。
Liberty リソース・サーバーは JWT クレームを使用して認証サブジェクトを作成し、ユーザーは、以下の
openidConnectClient エレメント属性で JWT クレームをサブジェクトにマップする方法を定義できます。
- userIdentifier
- userUniqueIdentifier
- groupIdentifier
- realmName
- realmIdentifier
realmName と
realmIdentifier の両方が構成されている場合は、
realmName が優先され、
realmIdentifier は無視されます。
クレームとサブジェクトのマッピングを定義しない場合、以下のデフォルト・マッピング・ルールが適用されます。
- サブジェクト (sub) クレームは、ユーザーのプリンシパル名および固有セキュリティー名として使用される。
- 発行者 (iss) クレームは、デフォルト・レルムであり、サブジェクト・レルムとして使用される。realmName クレームが JWT トークンに含まれている場合は、iss クレームではなく realmName クレームがサブジェクト・レルムとして使用される。
- オプション: シングル・サインオン Cookie を構成します。 Liberty サーバーは、各要求が有効な JWT トークンを提供することを予期しており、認証用にシングル・サインオン Cookie を作成または使用しません。シングル・サインオン Cookie を作成するには、openidConnectClient エレメントに authnSessionDisabled="false" を設定します。
- オプション: JWT トークンを受け取るように Liberty サーバーを構成します。Web クライアントは、次のいずれかのメソッドを使用して、Liberty リソース・サーバーへのリソース要求で JWT トークンを送信します。JWT トークンが Authorization フィールドまたはフォーム・エンコードされたボディ・パラメーターで送信された場合、追加のサーバー構成は必要ありません。
重要: クライアントは、トークンを送信するための各要求で複数のメソッドを使用してはいけません。headerName 属性が構成されている場合、Authorization ヘッダー・フィールドまたはフォーム・エンコードされたボディ・パラメーターで送信されるトークンは無視されます。headerName 属性が構成されていない場合は、Authorization ヘッダーが最初に検索され、その後に access_token パラメーターが検索されます。
- JWT オーディエンスを構成します。 信頼できるオーディエンスのリストを定義するには、openidConnectClient エレメントに audiences 属性を構成します。
有効な JWT トークンは、次のいずれかの条件を満たしている必要があります。
- audiences 属性が構成されている場合、オーディエンス (aud) クレーム値は、構成されているいずれかのオーディエンスでなければなりません。オーディエンス・チェックを無視するには、audiences を ALL_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
- オプション: com.ibm.wsspi.security.oauth.UserCredentialResolver サービス・プログラミング・インターフェース (SPI) を実装して、プログラマチックに JWT トークンをサブジェクトにマップします。
このインターフェースについて詳しくは、『プログラミング・インターフェース (Javadoc)』で、または、製品と一緒に ${wlp.install.dir}/dev/spi/ibm/ ディレクトリー内に提供される Java 文書で、com.ibm.wsspi.security.oauth.UserCredentialResolver SPI についての説明を参照してください。