第5章 Red Hat Single Sign-On 7.6 によってセキュリティー保護されたアプリケーションの移行
Red Hat build of Keycloak では、アプリケーションによる一部の Red Hat Single Sign-On 7.6 クライアントアダプターの使用方法に重要な変更が導入されています。
Red Hat build of Keycloak では、一部のクライアントアダプターのリリースが中止されることに加えて、クライアントアプリケーションによる OpenID Connect および SAML プロトコルの使用方法に影響を与える修正と改善も導入されています。
この章では、これらの変更に対処し、アプリケーションを移行して Red Hat build of Keycloak と統合する手順を説明します。
5.1. OpenID Connect クライアントの移行
Red Hat build of Keycloak のこのリリース以降、以下の Java クライアント OpenID Connect アダプターはリリースされなくなりました。
- Red Hat JBoss Enterprise Application Platform 6.x
- Red Hat JBoss Enterprise Application Platform 7.x
- Spring Boot
- Red Hat Fuse
これらのアダプターが最初にリリースされたときと比較して、OpenID Connect は Java エコシステム全体で広く利用できるようになりました。また、アプリケーションサーバーやフレームワークなどのテクノロジースタックから利用可能な機能を使用することにより、相互運用性とサポートが大幅に向上します。
これらのアダプターはサポートが終了しており、Red Hat Single Sign-On 7.6 からのみ利用可能です。OAuth2 および OpenID Connect プロトコルの最新の更新を使用してアプリケーションを最新の状態に保つための代替手段を探すことを強く推奨します。
5.1.1. OpenID Connect プロトコルとクライアント設定の主な変更点
5.1.1.1. Access Type クライアントオプションは利用不可
OpenID Connect クライアントの作成または更新時に Access Type が使用できなくなります。ただし、他の方法を使用してこの機能を実現することもできます。
- Bearer Only 機能を実現するには、認証フローを持たないクライアントを作成します。クライアントの詳細の Capability config セクションで、フローが選択されていないことを確認してください。クライアントは Keycloak からトークンを取得できません。これは、Bearer Only アクセスタイプを使用した場合と同じです。
- Public 機能を実現するには、このクライアントに対してクライアント認証が無効になっていて、少なくとも 1 つのフローが有効になっていることを確認してください。
- Confidential 機能を実現するには、クライアントに対して Client Authentication が有効になっていて、少なくとも 1 つのフローが有効になっていることを確認してください。
ブール値フラグの bearerOnly と publicClient は、クライアント JSON オブジェクトに引き続き存在します。これらは、管理 REST API によってクライアントを作成または更新するとき、または部分インポートまたはレルムインポートによってこのクライアントをインポートするときに使用できます。ただし、これらのオプションは管理コンソール v2 では直接使用できません。
5.1.1.2. 有効なリダイレクト URI の検証スキームの変更
アプリケーションクライアントが http(s) 以外のカスタムスキームを使用している場合、有効なリダイレクトパターンでそのスキームを明示的に許可することが検証に必要になりました。カスタムスキームを許可するパターンの例には、custom:/test、custom:/test/*、custom: などがあります。セキュリティー上の理由から、* などの一般的なパターンは、これらのスキームに対して無効になりました。
5.1.1.3. OpenID Connect ログアウトエンドポイントでの client_id パラメーターのサポート
client_id パラメーターをサポートします。これは、OIDC RP-Initiated Logout 1.0 仕様に基づいています。この機能は、id_token_hint パラメーターが使用できない場合に、ログアウト後の URI リダイレクト検証にどのクライアントを使用する必要があるかを検出するのに役立ちます。id_token_hint パラメーターを使用せずに client_id パラメーターのみを使用した場合でも、ログアウト確認画面をユーザーに表示する必要があります。そのため、ユーザーにログアウト確認画面を表示する必要がない場合は、クライアントに id_token_hint パラメーターを使用することを推奨します。
5.1.2. Valid Post Logout Redirect URI
Valid Post Logout Redirect URIs 設定オプションが OIDC クライアントに追加されました。これは、OIDC 仕様に準拠しています。ログインおよびログアウト後のリダイレクトには、別のリダイレクト URI セットを使用できます。Valid Post Logout Redirect URIs に使用される値 + は、Valid Redirect URIs オプションで指定されたのと同じリダイレクト URI のセットがログアウトに使用されることを意味します。この変更は、下位互換性のため、以前のバージョンから移行するときのデフォルトの動作にも一致します。
5.1.2.1. UserInfo エンドポイントの変更
5.1.2.1.1. エラー応答の変更
UserInfo エンドポイントが、RFC 6750 (The OAuth 2.0 Authorization Framework: Bearer Token Usage) に完全に準拠したエラー応答を返すようになりました。エラーコードと説明 (利用可能な場合) は、JSON オブジェクトフィールドではなく WWW-Authenticate チャレンジ属性として提供されます。
応答は、エラーの状態に応じて次のようになります。
アクセストークンが提供されていない場合:
401 Unauthorized WWW-Authenticate: Bearer realm="myrealm"
アクセストークンを提供するために複数の方法が同時に使用された場合 (たとえば、認可ヘッダー + POST access_token パラメーター)、または POST パラメーターが重複する場合:
400 Bad Request WWW-Authenticate: Bearer realm="myrealm", error="invalid_request", error_description="..."
アクセストークンに
openidスコープがない場合:403 Forbidden WWW-Authenticate: Bearer realm="myrealm", error="insufficient_scope", error_description="Missing openid scope"
UserInfo 応答の署名/暗号化の暗号鍵を解決できない場合:
500 Internal Server Error
トークン検証エラーの場合、
invalid_tokenエラーコードと併せて401 Unauthorizedが返されます。このエラーには、ユーザーおよびクライアント関連のチェックが含まれており、残りのすべてのエラーケースがキャプチャーされます。401 Unauthorized WWW-Authenticate: Bearer realm="myrealm", error="invalid_token", error_description="..."
5.1.2.1.2. UserInfo エンドポイントに対するその他の変更
アクセストークンに openid スコープが必要になりました。これは、OAuth 2.0 ではなく OpenID Connect に固有の機能である UserInfo によって規定されています。openid スコープがトークンにない場合、要求が 403 Forbidden として拒否されます。前のセクションを参照してください。
UserInfo がユーザーのステータスをチェックするようになり、ユーザーが無効な場合は、invalid_token 応答を返すようになりました。
5.1.2.1.3. Service Account Client のデフォルト Client ID マッパーの変更
Service Account Client のデフォルトの Client ID マッパーが変更されました。Token Claim Name フィールドの値が clientId から client_id に変更されました。client_id クレームは OAuth2 仕様に準拠しています。
clientId userSession ノートは引き続き存在します。
5.1.2.1.4. OAuth 2.0/OpenID Connect Authentication Response に iss パラメーターを追加
RFC 9207 OAuth 2.0 Authorization Server Issuer Identification 仕様で、セキュアな認証応答を実現するために、OAuth 2.0/OpenID Connect Authentication Response に iss パラメーターが追加されました。
過去のリリースにはこのパラメーターはありませんでしたが、仕様の要求に従って、Red Hat build of Keycloak にはデフォルトでこのパラメーターが追加されました。ただし、一部の OpenID Connect/OAuth2 アダプター、特に Red Hat build of Keycloak の古いアダプターでは、この新しいパラメーターで問題が発生する可能性があります。たとえば、クライアントアプリケーションへの認証に成功すると、パラメーターは常にブラウザー URL に表示されます。
このような場合、認証応答への iss パラメーターの追加を無効にすると役立つことがあります。これは、管理コンソールから、OpenID Connect Compatibility Modes を含むセクション内のクライアントの詳細で、特定のクライアントに対して行うことができます。Exclude Issuer From Authentication Response を有効にすると、認証応答への iss パラメーターの追加を回避できます。
