Securing Applications and Services Guide

OpenID Connect （OIDC）は OAuth 2.0 を拡張した認証プロトコルです。OAuth 2.0が認可プロトコルのみを構築するためのフレームワークで、不完全であるのに対し、OIDCは完成された認証および認可のプロトコルです。OIDCはまた、 Json Web Token （JWT）の標準セットを多用します。これらの標準は、コンパクトでWebフレンドリーな方法で、アイデンティティー・トークンのJSON形式とデジタル署名、データ暗号化の方法を定義します。

OIDCを使用するユースケースは、実際には2つの種類があります。1つ目は、Keycloakサーバーにユーザーの認証を要求するアプリケーションのユースケースです。ログインが成功すると、アプリケーションは IDトークン と アクセストークン を受け取ります。 IDトークン には、ユーザーに関する情報（ユーザー名、電子メール、その他のプロファイル情報など）が含まれています。 アクセストークン はレルムによってデジタル署名されており、アプリケーションがユーザーのアクセス可能なリソースを決定するために使用できるアクセス情報（ユーザー・ロール・マッピングのような）が含まれています。

2つ目のタイプは、リモートサービスへのアクセス権を取得したいクライアントのユースケースです。この場合、クライアントは、ユーザーの代理として他のリモートサービスの呼び出しに使用できる アクセストークン の取得をKeycloakに要求します。Keycloakは、ユーザーを認証し、クライアントのアクセスを許可する同意を要求します。そして、クライアントは アクセストークン を受け取ります。この アクセストークン はレルムによってデジタル署名されます。クライアントはこの アクセストークン を使用して、リモートサービスのREST呼び出しを行うことができます。REST サービスは アクセストークン を抽出し、トークンの署名を検証し、トークン内のアクセス情報に基づいて、リクエストを処理するかどうかを決定します。

SAML 2.0は、OIDCに似ていますが、それよりも古く成熟した仕様です。SOAPと過多なWS-*の仕様をそのルーツを持っているため、OIDCよりも少し冗長になる傾向があります。SAML 2.0は、主に認証サーバーとアプリケーション間のXMLドキュメントの交換によって動作する認証プロトコルです。XML署名と暗号化を使用して、リクエストとレスポンスを検証します。

Keycloakでは、SAMLはブラウザー・アプリケーションとREST呼び出しの2種類のユースケースを提供しています 。

SAMLを使用するユースケースは、実際には2つの種類があります。1つ目は、Keycloakサーバーにユーザーの認証を要求するアプリケーションのユースケースです。ログインが成功すると、アプリケーションはユーザーに関する様々な属性を指定するSAMLアサーションと呼ばれるものが含まれるXMLドキュメントを受け取ります。このXMLドキュメントはレルムによってデジタル署名されており、アプリケーションがユーザーのアクセス可能なリソースを決定するために使用できるアクセス情報（ユーザー・ロール・マッピングなど）が含まれています。

2つ目のタイプは、リモートサービスへのアクセス権を取得したいクライアントのユースケースです。この場合、クライアントは、ユーザーの代理として他のリモートサービスの呼び出しに使用できるSAMLアサーションの取得をKeycloakに要求します。

OpenID ConnectとSAMLの選択は、古いより成熟したプロトコル（SAML）の代わりに新しいプロトコル（OIDC）を使用するだけの問題ではありません。

ほとんどの場合において、KeycloakではOIDCを使用することをお勧めします。

SAMLは、OIDCよりも少し冗長になる傾向があります。

交換するデータの詳細度を度外視して仕様を比較した場合、OIDCはもともとWebで動作するように設計されていますが、SAMLはWeb上で動作するように改造されていることが分かります。たとえば、OIDCはSAMLよりもクライアントサイドに実装することが簡単なため、HTML5/JavaScriptアプリケーションにも適しています。トークンはJSON形式なので、JavaScriptにより簡単に扱うことができます。また、Webアプリケーションに対してセキュリティーの実装を容易にする、いくつかの素晴らしい機能があります。たとえば、ユーザーがログインしているかどうかを容易に判断するために使用する iframeトリック の仕様をチェックしてください。

SAMLにも用途はあります。OIDCの仕様の進化を見ると、SAMLが長年に渡って実装してきた多数の機能がOIDCにも実装されていることが分かります。SAMLがOIDCより成熟しているという認識と、SAMLによりセキュリティー保護されている既存のアプリケーションが存在するという理由により、OIDCよりもSAMLが選ばれることは多々あります。

Keycloakでサポートされている各Javaアダプターは、単純なJSONファイルで設定できます。これは、次のようになります。

システム・プロパティーの置換には ${…​} 囲みを使用することができます。例えば ${jboss.server.config.dir} は /path/to/Keycloak に置換されます。環境変数の置き換えも env 接頭辞でサポートされており、例えば ${env.MY_ENVIRONMENT_VARIABLE} のようになります。デフォルト値 ${…​:default_value} を定義することもでき、システム・プロパティー ${jboss.server.config.dir:default_value} 、または環境変数 ${env.MY_ENVIRONMENT_VARIABLE:default_value} が存在しない場合に使用されます。

初期設定ファイルは、管理コンソールから取得できます。これを行うには、管理コンソールを開き、メニューから Clients を選択し、対応するクライアントをクリックします。クライアントのページが開かれたら、 Installation タブをクリックし、 Keycloak OIDC JSON を選択します。

各設定オプションの説明は次のとおりです。

JBoss EAP、WildFly、またはJBoss ASにデプロイされたWARアプリケーションをセキュリティー保護するには、Keycloakアダプター・サブシステムをインストールして設定する必要があります。さらに、WARをセキュリティー保護する2つのオプションがあります。

どちらの方法も、このセクションで説明します。

アダプターは、使用しているサーバーのバージョンに応じて別個のアーカイブとして利用できます。

Tomcat 8、9上に配備されたWARアプリをセキュリティー保護するためには、TomcatのインストールにKeycloak Tomcatアダプターをインストールします。その後、Tomcatにデプロイする各WARをセキュリティー保護するための追加設定を行います。

Keycloakには、Jetty 9.4.x用の個別のアダプターがあります。これらをJettyにインストールする必要があります。Jettyにデプロイする各WARには、さらにいくつかの設定を行う必要があります。

Spring SecurityとKeycloakでアプリケーションを保護するには、このアダプターをプロジェクトのdependencyに追加します。Spring Securityの設定ファイルにいくつか追加のBeanを用意し、パイプラインにKeycloakセキュリティー・フィルターを追加する必要があります。

他のKeycloakアダプターとは異なり、web.xmlにセキュリティーを設定しないでください。ただし、 keycloak.json は依然として必要です。シングル・サインアウトが適切に機能するためには、セッション・リスナーを定義する必要があります。

KeycloakアダプターがないプラットフォームにJavaサーブレット・アプリケーションをデプロイする場合は、サーブレット・フィルター・アダプターを使用することを選択します。このアダプターは、他のアダプターとは多少動作が異なります。web.xmlにはセキュリティー制約を定義しません。代わりにKeycloakサーブレット・フィルター・アダプターを使用してフィルター・マッピングを定義して、URLパターンでセキュリティー保護します。

上記のスニペットには2つのURLパターンがあります。 /protected/* は保護したいファイルで、/keycloak/* のurl-patternはKeycloakサーバーからのコールバックを処理します。

設定された url-patterns の下にあるいくつかのパスを除外する必要がある場合は、keycloakフィルターが直ちにフィルター・チェーンに委譲すべきパス・パターンを記述する正規表現を設定するために、フィルターのinit-param keycloak.config.skipPattern を使用できます。デフォルトでは、skipPatternは設定されていません。

パターンは コンテキスト・パス なしで requestURI と照合されます。コンテキスト・パス /myapp が与えられると、 /myapp/index.html のリクエストは、スキップ・パターンと /index.html で照合されます。

Keycloak管理コンソールでクライアントのURLを設定する必要があります。Admin URLは、フィルターのurl-patternで保護されたセクションを指します。

Admin URLは、バックチャネル・ログアウトなどの操作を行うために、管Admin URLへのコールバックを行います。したがって、この例のAdmin URLは http[s]://hostname/{context-root}/keycloak でなければなりません。

セッションIDマッパーをカスタマイズする必要がある場合は、Filter init-param keycloak.config.idMapperでクラスの完全修飾名を設定することができます。セッションIDマッパーは、ユーザIDとセッションIDをマッピングするために使用されるマッパーです。デフォルトではorg.keycloak.adapters.spi.InMemorySessionIdMapperが設定されています。

Keycloakフィルターは、コンテキスト・パラメーターの代わりにフィルター初期化パラメーターとして定義する必要がある以外は、他のアダプターと同じ設定パラメーターを持ちます。

このフィルターを使用するには、WARのpomに次のmavenアーティファクトを含めます。

ほとんどのアプリケーションでJAASを使用する必要はありません。特にHTTPベースのアプリケーションの場合は、JAASを使用する必要はありません。 しかし、一部のアプリケーションやシステムは、依然として純粋なレガシーJAASソリューションに依存している場合があります。Keycloakは、このような状況に役立つ2つのログイン・モジュールを提供します。

提供されるログイン・モジュールは次のとおりです。

どちらのモジュールも次の設定プロパティーを使用します。

Keycloakは、システム・ブラウザーを介して認証ステップを実行することによって、 KeycloakInstalled アダプターを介したデスクトップ（たとえば、Swing、JavaFX）またはCLIアプリケーションのセキュリティー保護をサポートします。

KeycloakInstalled アダプターは、 desktop と manual のバリアントをサポートしています。デスクトップ・バリアントは、システム・クレデンシャルを収集するためにシステム・ブラウザーを使用します。手動バリアントは、ユーザー・クレデンシャルを STDIN から読み込みます。

KeycloakSecurityContext インターフェイスはトークンに直接アクセスする必要がある場合に利用できます。これは、トークンから追加の詳細情報（ユーザー・プロファイル情報など）を取得する場合や、Keycloakによって保護されているRESTfulサービスを呼び出す場合に便利です。

サーブレット環境では、セキュアな呼び出しで HttpServletRequest の属性として以下のようにセキュリティー・コンテキストを利用できます。

または、セキュアでないリクエストでは以下のように HttpSession からセキュリティー・コンテキストを利用できます。

Keycloakには、サーブレットベースのクライアント・アダプター用のエラー処理機能があります。認証でエラーが発生すると、Keycloakは HttpServletResponse.sendError() を呼び出します。 web.xml ファイル内にerror-pageを設定してエラーを処理することができます。Keycloakは400、401、403、500のエラーをスローできます。

Keycloakはまた、取得可能な HttpServletRequest 属性を設定します。属性名は、 org.keycloak.adapters.spi.AuthenticationError です。これは org.keycloak.adapters.OIDCAuthenticationError にキャストする必要があります。

例：

Webアプリケーションからのログアウトは複数の方法で行うことができる。Jakarta EEのサーブレット・コンテナーの場合、 HttpServletRequest.logout() を呼び出すことができます。その他のブラウザー・アプリケーションでは、ブラウザーを http://auth-server/realms/{realm-name}/protocol/openid-connect/logout にリダイレクトすることができ、そのユーザーがブラウザーでSSOセッションを持っていればログアウトされます。実際のログアウトは、ユーザーがログアウトを確認した後に行われます。 OpenID Connect RP-Initiated Logout で説明されているように、オプションで id_token_hint や post_logout_redirect_uri 、 client_id などのパラメーターを含めることができます。その結果、 id_token_hint パラメーターを指定した場合、そのログアウトはユーザーが明示的に確認する必要がなくなります。ログアウト後は、 post_logout_redirect_uri が指定されている限り、自動的に指定された場所にリダイレクトされます。なお、post_logout_redirect_uri が含まれている場合は、 client_id または id_token_hint パラメーターのいずれかを含める必要があります。

ログアウト・プロセスの一部として外部アイデンティティー･プロバイダーからログアウトしないようにするには、パラメーター initiating_idp を指定します。値は当該のアイデンティティー･プロバイダーのアイデンティティー（エイリアス）です。このパラメーターは、外部アイデンティティー･プロバイダーによって開始されたシングルログアウトの一部として、ログアウト・エンドポイントが呼び出された場合に便利です。 パラメーター initiating_idp は、RP-Initiated Logoutの仕様に記載されているパラメーターであり、 Keycloakのログアウト・エンドポイントでサポートされたパラメーターです。

HttpServletRequest.logout() を使用すると、アダプターはKeycloakサーバーに対して、バックチャネルでリフレッシュトークンを渡すPOSTリクエストを送信します。保護されていないページ（有効なトークンをチェックしていないページ）からメソッドが実行された場合、リフレッシュトークンは使用できない可能性があり、その場合はアダプターがPOSTリクエストの送信をスキップします。このため、現在のトークンが常に考慮され、必要に応じてKeycloakサーバーとの対話が実行されるように、保護されたページを使用して HttpServletRequest.logout() を実行することを推奨します。

Keycloakの初期認可エンドポイント・リクエストは、さまざまなパラメーターをサポートしています。ほとんどのパラメータは OIDC仕様 に記述されています。一部のパラメーターは、アダプターの設定に基づいて、アダプターにより自動的に追加されます。ただし、呼び出しごとに追加できるパラメーターもいくつかあります。保護されたアプリケーションURIにアクセスすると、特定のパラメーターはKeycloak認可エンドポイントにフォワードされます。

たとえば、オフライントークンを要求する場合、以下のように scope パラメーターを使用して保護されたアプリケーションのURIにアクセスできます。

パラメーター scope=offline_access が自動的にKeycloak認可エンドポイントにフォワードされます。

サポートされるパラメーターは次のとおりです。

ほとんどのパラメーターは OIDC仕様 に記載されています。唯一の例外はパラメーター kc_idp_hint です。これはKeycloak固有で、自動的に使用するアイデンティティー・プロバイダーの名前を含んでいます。詳細は Server Administration Guide の アイデンティティー・ブローカリング のセクションを参照してください。

コンフィデンシャルOIDCクライアントがバックチャネル・リクエストを送信する必要がある場合（たとえば、トークンのコードを交換したり、トークンをリフレッシュするような場合）、Keycloakサーバーに対して認証する必要があります。デフォルトでは、クライアントIDとクライアント・シークレット、署名付きJWTによるクライアント認証、またはクライアント・シークレットを使用した署名付きJWTによるクライアント認証の3つの方法でクライアントを認証します。

マルチテナンシーとは、単一のターゲット・アプリケーション（WAR）が複数のKeycloakのレルムで保護されることを意味します。レルムは、同じKeycloakインスタンスまたは異なるインスタンスに配置できます。

実際には、これはアプリケーションが複数の keycloak.json アダプター設定ファイルを持つ必要があることを意味します。

さまざまなコンテキストパスに異なるアダプター設定ファイルをデプロイして、WARの複数のインスタンスを作成することができます。しかし、これは不便かもしれませんし、コンテキストパス以外のものに基づいてレルムを選択するようにできます。

Keycloakはカスタムの設定リゾルバーを持つことができるので、各リクエストにどのアダプター設定が使われるかを選ぶことができます。

まずこれを達成するためには、 org.keycloak.adapters.KeycloakConfigResolver の実装を作成する必要があります。たとえば、以下のようになります。

また、以下のように web.xml の keycloak.config.resolver のcontext-paramでどの KeycloakConfigResolver 実装を使うかを設定する必要もあります。

この章では、JBoss EAP、WildFly、またはJBoss ASにデプロイされてクラスター化されたアプリケーションのサポートについて解説します。

アプリケーションが次のような場合には、いくつかのオプションがあります。

クラスタリングを扱うことは、通常のアプリケーションほど簡単ではありません。ブラウザーとサーバーサイド・アプリケーションの両方がKeycloakにリクエストを送信することになるため、ロードバランサーでスティッキー・セッションを有効にするほど簡単ではありません。

デフォルトでは、JavaScriptアダプターは、シングル・サイン・アウトが発生したかどうかを検出するために使用される非表示のiframeを作成します。これはネットワーク・トラフィックを必要とせず、代わりに特殊なステータス・クッキーを調べることによってステータスを取得します。この機能は、 init メソッドに渡されるオプションに checkLoginIframe: false を設定することで無効にできます。

このクッキーを直接参照することに頼るべきではありません。フォーマットは変更可能で、アプリケーションではなくKeycloakサーバーのURLに関連付けられています。

デフォルトで、JavaScriptアダプターは 認可コード フローを使用します。

このフローにより、Keycloakサーバーは認証トークンではなく、認可コードをアプリケーションに返します。ブラウザーがアプリケーションにリダイレクトされた後、JavaScriptアダプターは code をアクセス・トークンとリフレッシュ・トークンに交換します。

Keycloakは、Keycloakでの認証が成功した直後にアクセス・トークンが送信される インプリシット・フロー もサポートしています。これは、トークンに対してコードを交換する追加のリクエストが無いので、標準フローよりもパフォーマンスに優れる可能性がありますが、アクセス・トークンの有効期限が切れたときに影響があります。

ただし、URLフラグメントにアクセス・トークンを送信することはセキュリティー上の脆弱性となります。たとえば、Webサーバーのログやブラウザーの履歴からトークンが漏洩する可能性があります。

インプリシット・フローを有効にするには、Keycloak管理コンソールでクライアントの Implicit Flow Enabled フラグを有効にする必要があります。 init メソッドに implicit という値を持つ flow パラメータを渡す必要もあります：

注意すべき点の1つは、アクセス・トークンのみが提供され、リフレッシュ・トークンがないことです。つまり、アクセス・トークンが期限切れになると、アプリケーションはKeycloakへのリダイレクトを再度実行して、新しいアクセス・トークンを取得する必要があります。

Keycloakは ハイブリッド・フロー もサポートしています。

これは、管理コンソールでクライアントの Standard Flow Enabled と Implicit Flow Enabled フラグを有効にすることを要求します。Keycloakサーバーはコードとトークンの両方をアプリケーションに送信します。アクセス・トークンとリフレッシュ・トークンの交換ができる間、アクセス・トークンは即時使用できます。インプリシット・フローと同様に、アクセス・トークンがすぐに利用できるため、ハイブリッド・フローはパフォーマンスに優れています。しかし、トークンは引き続きURLに送信され、前述のセキュリティーの脆弱性が当てはまる可能性があります。

ハイブリッド・フローの1つの利点は、アプリケーションでリフレッシュ・トークンが利用可能になることです。

ハイブリッド・フローの場合、以下のようにパラメーター flow を値 hybrid で init メソッドに渡す必要があります。

Keycloakは Apache Cordova で開発されたハイブリッド・モバイルアプリをサポートしています。JavaScriptアダプターには、 cordova と cordova-native の2つのモードがあります。

デフォルトはcordovaで、アダプタータイプが設定されておらず、window.cordovaが存在する場合、アダプターは自動的に選択します。ログインすると、 InApp Browser が開き、ユーザーはKeycloakとやり取りした後、アプリを http://localhost にリダイレクトします。そのため、管理コンソールのクライアント設定のセクションで、このURLを有効なリダイレクトURIとしてホワイトリストに登録する必要があります。

このモードはセットアップが簡単ですが、いくつかの欠点もあります。

このサンプル・アプリケーションを使用して、開始します： https://github.com/keycloak/keycloak/tree/master/examples/cordova

代替モード cordova-native は異なるアプローチをとっています。システムのブラウザーを使用してログインページを開きます。ユーザーが認証されると、特別なURLを使用して、ブラウザーがアプリにリダイレクトされます。そこから、Keycloakアダプターは、URLからコードまたはトークンを読み取ってログインを完了できます。

ネイティブモードをアクティブにするには、次のようにアダプタータイプ cordova-native を init メソッドに渡します。

このアダプターには、次の2つの追加プラグインが必要でした。

アプリにリンクするための技術的詳細は、各プラットフォームで異なり、特別な設定が必要です。詳しい手順については、 ディープリンク・プラグインのドキュメント のAndroidおよびiOSのセクションを参照してください。

アプリを開くためのリンクには、カスタムスキーマ（つまり、 myapp://login または android-app://com.example.myapp/https/example.com/login ）と ユニバーサル・リンク（iOS））/ ディープリンク（Android）をクリックします。前者は設定が容易で、より確実に動作する傾向がありますが、後者はセキュリティーが強化され、ドメインの所有者のみが登録できます。カスタムURLはiOSでは推奨されていません。最良の信頼性を得るために、ユニバーサル・リンクとそれにcustom-urlリンクを持つ代替サイトを組み合わせて使用することをお勧めします。

さらに、Keycloakアダプターとの互換性を向上させるには、以下の手順を実行することをお勧めします。

ネイティブモードを使用する方法を示すサンプル・アプリケーションがあります: https://github.com/keycloak/keycloak/tree/master/examples/cordova-native

デフォルトでサポートされていない環境（Capacitorなど）でJavaScriptクライアントを実行する必要がある場合があります。このような未知の環境でJavasScriptクライアントを使用できるようにするために、カスタム・アダプターを渡すことができます。たとえば、サードパーティーのライブラリーがそのようなアダプターを提供して、JavaScriptクライアントを問題なく実行できるようにすることができます。

この特定のパッケージは存在しませんが、そのようなアダプターをクライアントに渡す方法の良い例を示しています。

独自のアダプターを作成することもできます。そのためには、 KeycloakAdapter インターフェイスで説明されているメソッドを実装する必要があります。たとえば、次のTypeScriptコードにより、すべてのメソッドが適切に実装されます。

もちろん、タイプ情報を省略してTypeScriptを使用せずにこれを行うこともできますが、インターフェイスを適切に実装することは、完全にあなた次第です。

JavaScriptアダプターは、Base64（window.btoaとwindow.atob）、HTML5 History API、およびオプションでPromise APIに依存しています。これらが利用できないブラウザー（IE9など）をサポートする必要がある場合は、Polyfillを追加する必要があります。

Polyfillライブラリーの例：

一部のブラウザーの最新バージョンでは、さまざまなCookieポリシーが適用され、ChromeのSameSiteやサードパーティーのCookieを完全にブロックするなど、サードパーティによるユーザーのトラッキングを防止しています。これらのポリシーは今後さらに制限が厳しくなり、他のブラウザによって採用され、最終的にサードパーティーのコンテキストのCookieが完全にサポートされなくなり、ブラウザーによってブロックされることが予想されます。これにより影響を受けるアダプター機能は、将来廃止される可能性があります。

JavaScriptアダプターは、Session Status iframe、 silent check-sso、および通常の（非サイレント） check-sso のサードパーティーCookieに依存しています。これらの機能は、機能が制限されているか、Cookieに関するブラウザーの制限に基づいて完全に無効になっています。アダプターはこの設定を検出しようとし、それに応じて反応します。

すでに Node.js がインストールされていると仮定して、アプリケーション用のフォルダーを作成します。

npm init コマンドを使ってアプリケーション用の package.json を作成してください。依存関係リストにKeycloak接続アダプターを追加します。

プロジェクトのルートディレクトリーに server.js というファイルを作成し、以下のコードを追加します。

以下のように express-session の依存関係をインストールします。

server.js スクリプトを起動するには、 package.json の 'scripts' のセクションに以下のコマンドを追加します。

これで、次のコマンドでサーバーを実行できるようになりました。

デフォルトでは、アプリケーションのメインの実行ファイルとともに（ここではルートフォルダーに）、 keycloak.json というファイルを配置し、公開鍵、レルム名、各種 URL などのKeycloak固有の設定を初期化します。

その場合、Keycloakの管理コンソールにアクセスするためには、Keycloakのデプロイが必要です。

Podman または Docker でKeycloakの管理コンソールをデプロイする方法については、リンクを参照してください。

Keycloakの管理コンソールで → clients (left sidebar) → クライアントを選択 → Installation → Format Option → Keycloak OIDC JSON → Download で keycloak.json ファイルを入手する準備ができました。

ダウンロードしたファイルを、プロジェクトのルートフォルダーにペーストします。

このメソッドでインスタンス化すると、合理的なデフォルトが使用されます。代替として、 keycloak.json ファイルではなく、次のように設定オブジェクトを提供することも可能です。

アプリケーションは、次の方法を使用して、ユーザーを優先度の高いアイデンティティー・プロバイダーにリダイレクトすることもできます。

インスタンス化が完了したら、Middlewareをconnectに対応したアプリケーションにインストールします。

そのためには、まず、以下のようにExpressをインストールする必要があります。

以下のようなプロジェクトでExpressを必要としています。

次のコードの下に追加し、ExpressでKeycloakのミドルウェアを設定します。

最後に、 main.js に以下のコードを追加して、ポート3000でHTTPリクエストをリッスンするようにサーバーをセットアップしてみましょう。

SSL接続を終了するプロキシーの背後でアプリケーションが実行されている場合は、 express behind proxies ガイドに従ってExpressを設定する必要があります。不適切なプロキシー設定を使用すると、無効なリダイレクトURIが生成される可能性があります。

設定例：

別の アプリケーションのアプリケーション・ロールでリソースを保護するには次のようにします。

レルムロールを使用してリソースを保護するには次のようにします。

keycloak-enforcer メソッドは、 response_mode 設定オプションの値に応じて2つのモードで動作します。

response_mode が token に設定されている場合、パーミッションはアプリケーションに送られたベアラートークンによって表されるサブジェクトに代わりにサーバーから取得されます。この場合、Keycloakによって付与されたパーミッションとともに新しいアクセストークンが発行されます。サーバーが想定したパーミッションを持つトークンで応答しなかった場合、リクエストは拒否されます。このモードを使用するときは、次のようにリクエストからトークンを取得できるはずです。

アプリケーションがセッションを使用していて、サーバーからの以前の決定をキャッシュしたい場合や、自動的に更新トークンを処理したい場合は、このモードを選択してください。このモードは、クライアントおよびリソースサーバーとして機能するアプリケーションに特に役立ちます。

response_mode が permissions に設定されている場合（デフォルトモード）、サーバーは新しいアクセストークンを発行せずに、許可されたパーミッションのリストのみを返します。新しいトークンを発行しないことに加えて、このメソッドは以下のように request を介してサーバーにより与えられたパーミッションを公開します。

response_mode が使われているかどうかにかかわらず、 keycloak.enforcer メソッドは最初にアプリケーションに送られたベアラートークンの中のパーミッションをチェックしようとします。ベアラートークンがすでに想定されたパーミッションを持っている場合は、決定を得るためにサーバーと対話する必要はありません。これは、保護されたリソースにアクセスする前に、クライアントが期待されるパーミッションでサーバーからアクセストークンを取得できる場合に特に役立ちます。そのため、クライアントは増分認可などのKeycloak認可サービスによって提供される機能を使用できます。 keycloak.enforcer はリソースへのアクセスを強制します。

デフォルトでは、ポリシー・エンフォーサーはアプリケーションに定義された client_id を使って（たとえば keycloak.json を介して）、Keycloakの認可サービスをサポートするKeycloakのクライアントを参照します。この場合、クライアントは実際にはリソースサーバーであるため、パブリックにすることはできません。

アプリケーションがパブリック・クライアント（フロントエンド）とリソースサーバー（バックエンド）の両方として機能している場合は、次の設定を使用して、施行したいポリシーでKeycloak内の別のクライアントを参照できます。

フロントエンドとバックエンドを表すために、Keycloakで個別のクライアントを使用することをお勧めします。

保護しているアプリケーションがKeycloak認可サービスで有効になっていて、 keycloak.json でクライアントのクレデンシャルを定義している場合は、決定を下すために、追加のクレームをサーバーにプッシュし、それらをポリシーで利用できるようにすることができます。そのために、プッシュしたいクレームを持つJSONを返す function を期待する claim 設定オプションを定義できます。

アプリケーションのリソースを保護するようにKeycloakを設定する方法の詳細については、 Authorization Services Guide をご覧ください。

高度なログイン設定：

デフォルトでは、クライアントがbearer-onlyでない限り、許可されていないすべてのリクエストはKeycloakのログインページにリダイレクトされます。ただし、コンフィデンシャル・クライアントまたはパブリック・クライアントは、閲覧可能なエンドポイントとAPIエンドポイントの両方をホストする場合があります。認証されていないAPIリクエストでのリダイレクトを防ぎ、代わりにHTTP 401を返すようにするために、redirectToLogin関数をオーバーライドできます。

たとえば、このオーバーライドは、URLに/api/が含まれているかどうかを確認し、ログイン・リダイレクトを無効にします。

ユーザートリガーのログアウトが呼び出されると、次のようにクエリー・パラメーター redirect_url を渡すことができます。

このパラメーターはOIDCログアウト・エンドポイントのリダイレクトURLとして使用され、ユーザーは https://example.com/logged/out にリダイレクトされます。

Node.jsのアダプターを使用した完全な例は、 Keycloak quickstarts for Node.js で見ることができます。

理解すべき最も重要なエンドポイントは、 well-known 設定エンドポイントです。これは、KeycloakのOpenID Connectの実装に関連するエンドポイントとその他の設定オプションを一覧化します。エンドポイントは次のとおりです。

完全なURLを取得するには、KeycloakのベースURLを追加し、 {realm-name} をレルム名で置換します。以下に例を示します。

http://localhost:8080/realms/master/.well-known/openid-configuration

一部のRPライブラリーは、このエンドポイントから必要なすべてのエンドポイントを取得しますが、他はエンドポイントを個別に記載する必要があります。

Keycloakによって発行されたアクセストークンを手動で検証する必要がある場合は、イントロスペクション・エンドポイントを呼び出すことができます。このアプローチの欠点は、Keycloakサーバーへのネットワーク呼び出しが必要であることです。これは、同時に実行される検証リクエストが多すぎると、サーバーの速度を低下させ、過剰な負荷をかかる可能性があります。Keycloakが発行したアクセストークンは JSON Web Tokens（JWT） であり、 JSON Web Signature（JWS） によりデジタル署名されています。このようにエンコードされているため、発行したレルムの公開鍵を使用してアクセストークンをローカルで検証できます。レルムの公開鍵を検証コードにハードコードするか、証明書エンドポイントを使用してJWSに埋め込まれたKey ID（KID）を使用して公開鍵を検索してキャッシュすることができます。コーディングする言語に応じて、JWS検証の手助けをするサードパーティー・ライブラリーが多数あります。

リダイレクト・ベースのフローを使用する場合は、クライアントで有効なリダイレクトURLを使用することが重要です。リダイレクトURLはできるだけ具体的にする必要があります。これは、特にクライアント・サイド（パブリック・クライアント）のアプリケーションに適用されます。そうしないと次のことが起こる可能性があります。

Webアプリケーション用のプロダクション環境では、常にすべてのリダイレクトURIに https を使用します。httpへのリダイレクトは許可しないでください。

また、次のような特別なリダイレクトURIがいくつかあります。

クライアントがFAPIに準拠していることを確認するには、 Server Administration Guide で説明されているように、レルムでクライアント・ポリシーを設定し、それらをFAPIサポートのグローバル・クライアント・プロファイルにリンクします。これは各レルムで自動的に利用可能になります。クライアントが準拠する必要のあるFAPIプロファイルに基づいて、 fapi-1-baseline または fapi-1-advanced プロファイルのいずれかを使用できます。

Pushed Authorization Request（PAR） を使いたい場合、クライアントはPARリクエストに対して fapi-1-baseline プロファイルと fapi-1-advanced プロファイルの両方を使用することが推奨されます。特に、fapi-1-baseline プロファイルは pkce-enforcer Executorを含んでおり、クライアントが安全なS256アルゴリズムのPKCEを使用することを確認します。FAPI Advancedクライアントの場合、PARリクエストを使用しない限り、これは必要ありません。

FAPIに準拠した方法でCIBAを使用したい場合、クライアントが fapi-1-advanced と fapi-ciba の両方のクライアント・プロファイルを使用していることを確認してください。 fapi-ciba プロファイルはCIBA固有のExecutorだけを含んでいるので、 fapi-1-advanced プロファイルか、要求されたExecutorを含む他のクライアント・プロファイルを使用する必要があります。FAPI CIBA仕様の要件を強制する場合、コンフィデンシャル・クライアントの強制や証明書バウンドのアクセストークンなど、より多くの要件が必要です。

Keycloakは、 Open Banking Brasil Financial-grade API Security Profile 1.0 Implementers Draft 1 に準拠しています。これはFAPI 1 Advanced仕様よりもいくつかの要件がより厳しく、したがって、いくつかの要件を強制するために、より厳しい方法で クライアント・ポリシー を構成する必要があるかもしれません。特に、以下の部分です。

機密情報をやり取りするため、全てのやり取りをTLS（HTTPS）で暗号化しなければなりません。さらに、FAPIの仕様には、使用する暗号スイートとTLSプロトコルのバージョンに関するいくつかの要件があります。これらの要件に合わせるために、許可される暗号の設定を検討することができます。この設定は https-protocols と https-cipher-suites オプションを設定することで行うことができます。Keycloakはデフォルトで TLSv1.3 を使用しているため、デフォルトの設定を変更する必要はないでしょう。しかし、何らかの理由で低いバージョンのTLSにフォールバックする必要がある場合は、暗号を調整する必要があるかもしれません。詳しくは、 TLSの設定 ガイドを参照してください。

KeycloakでサポートされているSAMLクライアント・アダプターは、いずれも簡単なXMLテキストファイルで設定できます。これは以下のようなものです。

これらの設定の中には、アダプター固有のものもあれば、すべてのアダプターに共通のものもあります。Javaアダプターの場合は、システム・プロパティーの置換に ${…​} エンクロージャーを使用できます。 たとえば、 ${jboss.server.config.dir} です。

JBoss EAPまたはWildFlyにデプロイされたWARアプリケーションを保護するには、Keycloak SAMLアダプター・サブシステムをインストールして設定する必要があります。

そして、WARにkeycloakの設定ファイルである /WEB-INF/keycloak-saml.xml を用意し、web.xml内のauth-methodをKEYCLOAK-SAMLに変更します。

各アダプターは、Keycloakのダウンロード・サイトで個別にダウンロードできます。

スクリプトは、以下に説明するように、extension、subsystem、オプションでsecurity-domainを追加します。

セキュリティー保護されたWeb層で作成されたセキュリティー・コンテキストを呼び出すEJB（他のEEコンポーネント）に伝播する必要がある場合は、 keycloak セキュリティー・ドメインをEJBなどのコンポーネントとともに使用する必要があります。それ以外の場合、この設定はオプションです。

セキュリティー・コンテキストは、EJB層に自動的に伝播されます。

Tomcat 8または9にデプロイされたWARアプリケーションをセキュリティー保護するには、Keycloak Tomcat SAMLアダプターをTomcatにインストールする必要があります。その後、TomcatにデプロイするWARにもいくつかの設定を行う必要があります。

JettyにデプロイされたWARアプリケーションを保護するには、Keycloak Jetty 9.4 SAMLアダプターをJettyにインストールします。その後、JettyにデプロイするWARにもいくつかの設定を行う必要があります。

以下のインストール手順と設定手順を使用してください。

サーブレット・プラットフォーム用のアダプターを持たないJavaサーブレット・アプリケーションでSAMLを使用する場合は、Keycloakにあるサーブレット・フィルター・アダプターを使用することができます。このアダプターは、他のアダプターとは少し異なります。共通アダプター設定セクションで定義されているように /WEB-INF/keycloak-saml.xml ファイルを指定する必要がありますが、 web.xml にセキュリティー制約を定義しません。代わりにKeycloakサーブレット・フィルター・アダプターを使用してフィルター・マッピングを定義して、URLパターンでセキュリティー保護します。

Keycloakフィルターは、コンテキスト・パラメータの代わりにフィルター初期化パラメータとして定義する必要がある以外は、他のアダプターと同じ設定パラメータを使用できます。

さまざまな異なる安全なURLパターンと安全でないURLパターンが存在する場合は、複数のフィルター・マッピングを定義できます。

IdPとともにSPを登録するときは、Assert Consumer Service URLとSingle Logout Service URLとして http[s]://hostname/{context-root}/saml を登録する必要があります。

このフィルターを使用するには、WARのpomに次のmavenアーティファクトを含めます。

マルチテナンシーを使用するには、 keycloak.config.resolver パラメーターをフィルター・パラメーターとして渡す必要があります。

サーブレット・ベース・アダプターごとに、アサート・コンシューマー・サービスURLとシングル・ログアウト・サービスURLに登録するエンドポイントは、 /saml が付加されるサーブレット・アプリケーションのベースURLでなければなりません。つまり、 https://example.com/contextPath/saml のようなURLになります。

Webアプリケーションからログアウトするには、複数の方法があります。Jakarta EEサーブレット・コンテナーの場合は、 HttpServletRequest.logout() を呼び出すことができます。他のブラウザーアプリケーションでは、ブラウザーにセキュリティー制約のあるWebアプリケーションのURLを指定し、クエリー・パラメーターGLO、つまり、 http://myapp?GLO=true を渡すことができます。これにより、ブラウザーとのSSOセッションがある場合は、ログアウトされます。

SAMLログインが成功したら、アプリケーションのコードで、SAMLアサーションに渡された属性値を取得したい場合があるかもしれません。 HttpServletRequest.getUserPrincipal() は、 org.keycloak.adapters.saml.SamlPrincipal と呼ばれるKeycloak特有のクラスにキャスト可能な、 Principal オブジェクトを返します。このオブジェクトには、未加工のアサーションを参照したり、属性値を取得する便利な機能があります。

Keycloakには、サーブレットベースのクライアント・アダプター用のエラー処理機能があります。認証でエラーが発生すると、クライアント・アダプターは HttpServletResponse.sendError() を呼び出します。 web.xml ファイル内にerror-pageを設定してエラーを処理することができます。クライアント・アダプターは、400、401、403、500のエラーをスローできます。

クライアント・アダプターはまた、取得可能な HttpServletRequest 属性を設定します。属性名は、 org.keycloak.adapters.spi.AuthenticationError です。このオブジェクトを org.keycloak.adapters.saml.SamlAuthenticationError にキャストします。このクラスは、正確に何が起こったかを伝えることができます。この属性が設定されない場合、アダプターはエラーコードに対して何もしません。

問題を解決する最善の方法は、SAMLクライアント・アダプターとKeycloakサーバーの両方でデバッギングを有効にすることです。ロギング・フレームワークを使用して、 org.keycloak.saml パッケージのログ・レベルを DEBUG に設定します。これを有効にすることで、サーバー間で送信されるSAMLのリクエスト/レスポンスのドキュメントを見ることができます。

SAMLは、マルチテナンシー についてOIDCと同じ機能を提供します。つまり、単一のターゲット・アプリケーション（WAR）を複数のKeycloakレルムで保護できます。レルムは、同じKeycloakインスタンスまたは異なるインスタンスに配置できます。

これを行うには、アプリケーションは複数の keycloak-saml.xml アダプター設定ファイルを持つ必要があります。

異なるコンテキストパスに異なるアダプター設定ファイルをデプロイして、WARの複数のインスタンスを作成することができますが、これは不便であり、コンテキストパス以外のものに基づいてレルムを選択することもできます。

Keycloakではカスタム設定リゾルバーを持つことが可能なため、どのアダプター設定が各リクエストに使用されるかを選択することができます。SAMLでは、設定はログイン処理においてのみ関係しています。ユーザーがログインするとセッションは認証され、返される keycloak-saml.xml が異なっていても問題ありません。そのため、同じセッションに対して同じ設定を返すことが正しい方法です。

これを実現するためには、 org.keycloak.adapters.saml.SamlConfigResolver の実装を作成してください。次の例では Host ヘッダーを使って適切な設定を見つけ、それとアプリケーションのJavaクラスパスから関連する要素をロードしています。

また、以下のように、 web.xml の keycloak.config.resolver context-paramでどの SamlConfigResolver 実装を使うかを設定する必要もあります。

関連するホストは2つあります。

次のすべての手順は、root特権で$sp_hostに対して実行される必要があります。

ブラウザーは、Cookieの SameSite 属性のデフォルト値を Lax に設定することを計画しています。この設定は、リクエストが同じドメインで発生した場合にのみCookieがアプリケーションに送信されることを意味します。この動作はSAML POSTバインディングに影響を与え、機能しなくなる可能性があります。 mod_auth_mellon モジュールの完全な機能を保持するために、 mod_auth_mellon モジュールによって作成されたCookieの SameSite 値を None に設定することをお勧めします。そうしないと、Keycloakを使用してログインできなくなる場合があります。

SameSite の値を None に設定するには、次の設定を mellon.conf ファイル内の <Location / > タグに追加します。