サーバー管理ガイド

次のセクションでは、既知のサードパーティソフトウェア SMTP サーバーで XOAUTH2 ベースの認証を使用するように Keycloak メール設定を構成する方法に関するヒントをいくつか示します。

ロケールセレクタープロバイダーは、利用可能な情報に基づいて最適なロケールを提案します。ただし、ユーザーが誰であるかは不明な場合がよくあります。このため、以前に認証されたユーザーのロケールは、永続化された Cookie に記憶されます。

ロケールを選択するロジックは、次のうち最初に利用可能なものを使用します。

ユーザーが認証されると、前に述べた永続化された Cookie 内のロケールを更新するアクションがトリガーされます。ユーザーがログインページでロケールセレクターを介してロケールを積極的に切り替えた場合、この時点でユーザーのロケールも更新されます。

ロケールを選択するロジックを変更したい場合は、カスタムの LocaleSelectorProvider を作成するオプションがあります。詳細については、サーバー開発者ガイドを参照してください。

パスワードを忘れた場合を有効にすると、ユーザーはパスワードを忘れたり、OTP ジェネレーターを紛失した場合に、ログイン資格情報をリセットできます。

メールで送信されるテキストは設定可能です。詳細については、サーバー開発者ガイドを参照してください。

ユーザーがメールリンクをクリックすると、Keycloak はパスワードの更新を求め、OTP ジェネレーターを設定している場合は、OTP ジェネレーターの再設定を求めます。セキュリティ上の理由から、このフローはフェデレーションユーザーに資格情報のリセット後に再度ログインするように強制し、同じ認証セッション（同じブラウザ）が使用されている場合は、内部データベースユーザーをログイン状態に保ちます。組織のセキュリティ要件に応じて、デフォルトの動作を変更できます。

この動作を変更するには、次の手順を実行します。

ログインしたユーザーがブラウザを閉じるとセッションが破棄され、そのユーザーは再度ログインする必要があります。ユーザーがログイン時にRemember Meチェックボックスをオンにした場合、Keycloak がユーザーのログインセッションを開いたままにするように設定できます。このアクションにより、ログイン Cookie がセッションのみの Cookie から永続 Cookie に変わります。

レルムの一般設定では、どの認証コンテキストクラス参照 (ACR) 値をどの認証レベル (LoA) にマッピングするかを定義できます。ACR は任意の値にできますが、LoA は数値である必要があります。acr クレームは、OIDC リクエストで送信される claims または acr_values パラメーターでリクエストでき、アクセストークンと ID トークンにも含まれます。マッピングされた数値は、認証フロー条件で使用されます。

特定のクライアントがレルムとは異なる値を使用する必要がある場合に備えて、マッピングはクライアントレベルでも指定できます。ただし、ベストプラクティスはレルムマッピングに固執することです。

詳細については、ステップアップ認証および公式 OIDC 仕様を参照してください。

このワークフローでは、ユーザーは自分のメールアドレスを変更するために UPDATE_EMAIL アクションを使用する必要があります。

このアクションは、単一のメール入力フォームに関連付けられています。レルムでメール検証が無効になっている場合、このアクションにより、検証なしでメールを更新できます。レルムでメール検証が有効になっている場合、このアクションはアカウントメールを変更せずに、新しいメールアドレスにメール更新アクショントークンを送信します。アクショントークンのトリガーのみがメールの更新を完了します。

アプリケーションは、AIA (アプリケーション開始アクション) として UPDATE_EMAIL を利用することにより、ユーザーをメール更新フォームに送信できます。

キーを定期的にローテーションすることをお勧めします。まず、既存のアクティブキーよりも優先度の高い新しいキーを作成します。代わりに、同じ優先度で新しいキーを作成し、以前のキーをパッシブにすることもできます。

新しいキーが利用可能になると、すべての新しいトークンと Cookie は新しいキーで署名されます。ユーザーがアプリケーションに対して認証を行うと、SSO Cookie が新しい署名で更新されます。OpenID Connect トークンが更新されると、新しいトークンは新しいキーで署名されます。最終的に、すべての Cookie とトークンが新しいキーを使用し、しばらくすると古いキーを削除できます。

古いキーを削除する頻度は、セキュリティと、すべての Cookie とトークンが更新されていることを確認することとのトレードオフです。新しいキーを 3 ～ 6 か月ごとに作成し、新しいキーを作成してから 1 ～ 2 か月後に古いキーを削除することを検討してください。新しいキーが追加されてから古いキーが削除されるまでの期間にユーザーが非アクティブだった場合、そのユーザーは再認証する必要があります。

キーのローテーションは、オフライン トークンにも適用されます。オフライン トークンが更新されるようにするには、アプリケーションは古いキーが削除される前にトークンを更新する必要があります。

自己署名証明書を含むキーペアを生成するには、次の手順を使用します。

プロバイダーの優先度を変更しても、キーが再生成されることはありませんが、キーサイズを変更する場合は、プロバイダーを編集すると新しいキーが生成されます。

RSA 生成キーペアから証明書を抽出し、その証明書を新しいキーストアで使用することで、キーをローテーションできます。

別の場所で取得したキーペアと証明書を追加するには、「Providers」を選択し、ドロップダウンから「rsa」を選択します。優先度を変更して、新しいキーペアがアクティブなキーペアになるようにすることができます。

ホスト上の Java キーストアファイルに保存されているキーペアと証明書を追加するには、「Providers」を選択し、ドロップダウンから「java-keystore」を選択します。優先度を変更して、新しいキーペアがアクティブなキーペアになるようにすることができます。

関連付けられた証明書チェーンをロードするには、キーペアのロードに使用したのと同じ「Key Alias (キーエイリアス)」を使用して Java キーストアファイルにインポートする必要があります。

Keycloak は署名キーをローカルにのみ保存しており、クライアントアプリケーション、ユーザー、またはその他のエンティティと共有されることはありません。ただし、レルム署名キーが侵害されたと思われる場合は、まず上記の説明に従って新しいキーペアを生成し、侵害されたキーペアを直ちに削除する必要があります。

または、「Providers (プロバイダー)」テーブルからプロバイダーを削除することもできます。

not-before ポリシーをプッシュすると、クライアントアプリケーションが侵害されたキーによって署名された既存のトークンを受け入れなくなります。クライアントアプリケーションも Keycloak から新しいキーペアをダウンロードする必要があるため、侵害されたキーによって署名されたトークンは無効になります。

Keycloak は、LDAP からローカルの Keycloak ユーザーデータベースにユーザーをインポートします。ユーザーデータベースのこのコピーは、オンデマンドまたは定期的なバックグラウンドタスクを通じて同期されます。パスワードの同期には例外があります。Keycloak はパスワードをインポートしません。パスワード検証は常に LDAP サーバーで実行されます。

同期の利点は、必要な追加のユーザーごとのデータがローカルに保存されるため、すべての Keycloak 機能が効率的に動作することです。欠点は、Keycloak が特定のユーザーを初めてクエリするたびに、対応するデータベース挿入を実行することです。また、インポートされたユーザーが検索操作の一部として返される場合、ユーザーが LDAP にまだ存在するかどうかを確認し、基本的な検証を行うために、それぞれに対応する LDAP 検索が実行されます。

LDAP マッパーが常にデータベースではなく LDAP から特定の属性を読み取る場合、インポートの同期は不要です。

Keycloak ユーザーデータベースにユーザーをインポートせずに、Keycloak で LDAP を使用できます。LDAP サーバーは、Keycloak ランタイムが使用する共通ユーザーモデルをバックアップします。LDAP が Keycloak 機能に必要なデータをサポートしていない場合、その機能は動作しません。このアプローチの利点は、LDAP ユーザーのコピーを Keycloak ユーザーデータベースにインポートおよび同期するリソースを使用しないことです。

LDAP 構成ページの「Import Users (ユーザーをインポート)」スイッチは、このストレージモードを制御します。ユーザーをインポートするには、このスイッチを「ON (オン)」に切り替えます。

ユーザーと管理者は、ユーザーメタデータを変更できます。ユーザーはアカウントコンソールを通じて、管理者は管理コンソールを通じて変更できます。LDAP 構成ページの「Edit Mode (編集モード)」構成は、ユーザーの LDAP 更新権限を定義します。

同様のプロパティは、グループおよびロールマッパーでも使用でき、グループとロールをグループ/ロールの検索に使用されるベース DN のサブ DN に追加できます。

LDAP ストアへのセキュア接続 URL (たとえば、ldaps://myhost.com:636) を構成すると、Keycloak は SSL を使用して LDAP サーバーと通信します。Keycloak が LDAP への SSL 接続を信頼できるように、Keycloak サーバー側でトラストストアを構成します。詳細については、トラストストアの構成ガイドを参照してください。

「Use Truststore SPI (トラストストア SPI を使用)」構成プロパティは非推奨です。通常は「Always (常に)」のままにする必要があります。

インポートユーザーオプションを設定すると、LDAPプロバイダーはLDAPユーザーをKeycloakローカルデータベースにインポート処理します。ユーザーが初めてログインするか、ユーザークエリの一部として返される（例えば、管理コンソールの検索フィールドを使用）と、LDAPプロバイダーはLDAPユーザーをKeycloakデータベースにインポートします。認証中、LDAPパスワードが検証されます。

すべてのLDAPユーザーをKeycloakデータベースに同期したい場合は、LDAPプロバイダー設定ページで同期設定を構成して有効にします。

同期には2つのタイプがあります。

同期の最良の方法は、LDAPプロバイダーを最初に作成するときにすべてのユーザーを同期をクリックし、その後、変更されたユーザーの定期的同期を設定することです。

LDAPマッパーは、LDAPプロバイダーによってトリガーされるリスナーです。これらは、LDAP統合への別の拡張ポイントを提供します。LDAPマッパーは、以下の場合にトリガーされます。

LDAPフェデレーションプロバイダーを作成すると、Keycloakは自動的にこのプロバイダー用のマッパーのセットを提供します。このセットはユーザーが変更可能であり、ユーザーはマッパーを開発したり、既存のマッパーを更新/削除したりすることもできます。

ユーザー名、firstName、lastName、emailなどの基本的なKeycloakユーザー属性を、対応するLDAP属性にマップするユーザー属性マッパー。これらを拡張して、独自の追加属性マッピングを提供できます。管理コンソールには、対応するマッパーの構成に役立つツールチップが用意されています。

Keycloakがパスワードを更新するとき、Keycloakはプレーンテキスト形式でパスワードを送信します。このアクションは、組み込みのKeycloakデータベースでパスワードを更新する場合とは異なります。組み込みのKeycloakデータベースでは、Keycloakはパスワードをハッシュ化およびソルト化してからデータベースに送信します。LDAPの場合、KeycloakはLDAPサーバーにパスワードのハッシュ化とソルト化を依存します。

デフォルトでは、MSAD、RHDS、FreeIPAなどのLDAPサーバーはパスワードをハッシュ化およびソルト化します。OpenLDAPやApacheDSなどの他のLDAPサーバーは、RFC3062で説明されているLDAPv3パスワード変更拡張操作を使用しない限り、パスワードをプレーンテキストで保存します。LDAP構成ページでLDAPv3パスワード変更拡張操作を有効にします。詳細については、LDAPサーバーのドキュメントを参照してください。

LDAP接続を管理する際の効率を高め、複数の接続を処理する際のパフォーマンスを向上させるために、接続プーリングを有効にすることができます。これにより、接続が閉じられると、将来の使用のためにプールに戻され、常に新しい接続を作成するコストが削減されます。

LDAP接続プール構成は、次のシステムプロパティを使用して構成されます。

デフォルトでは、接続プーリングはplainプロトコルとsslプロトコルの両方で有効になっています。

詳細については、Java LDAP接続プーリング構成ドキュメントを参照してください。

これらのプロパティを設定するには、JAVA_OPTS_APPEND環境変数を設定できます。

カテゴリorg.keycloak.storage.ldapのロギングレベルをTRACEに上げることは有用です。この設定では、LDAPサーバーへのすべてのクエリと、クエリの送信に使用されたパラメーターを含む、多くのロギングメッセージがTRACEレベルでサーバーログに送信されます。ユーザーフォーラムまたはJIRAでLDAPに関する質問を作成する場合は、TRACEロギングを有効にしたサーバーログを添付することを検討してください。大きすぎる場合は、問題を引き起こしている操作中にログに追加されたメッセージを含むサーバーログからのスニペットのみを含めることが適切な代替手段です。

これは、LDAPプロバイダーの構成を示しています。質問をしたり、バグを報告する前に、このメッセージを含めてLDAP構成を示すと良いでしょう。最終的には、含めたくない構成の変更をプレースホルダー値に置き換えても構いません。1つの例はbindDn=some-placeholderです。connectionUrlについても、同様に置き換えても構いませんが、使用されたプロトコル（ldap対ldaps）を少なくとも含めることが一般的に役立ちます。同様に、DEBUGレベルで次のようなメッセージで表示されるLDAPマッパーの構成の詳細を含めることも役立ちます。

これらのメッセージは、DEBUGロギングが有効になっている場合にのみ表示されることに注意してください。

サーバーを再起動しても接続プーリングに関するメッセージが表示されない場合は、接続プーリングがLDAPサーバーで動作していないことを示している可能性があります。

FreeIPAコンテナイメージは、Quay.ioで入手できます。FreeIPAサーバーをセットアップするには、FreeIPAドキュメントを参照してください。

フェデレーションプロバイダーは、D-BUSを使用してSSSDからデータを取得します。PAMを使用してデータを認証します。

Keycloakは、D-Busと低レベルで通信するためにDBus-Javaプロジェクトを使用し、オペレーティングシステムのPluggable Authentication Modules（PAM）を介して認証するためにJNAを使用します。

現在、KeycloakはSSSDプロバイダーを実行するために必要なすべてのライブラリを含んでいますが、JDKバージョン21が必要です。したがって、SSSDプロバイダーは、ホスト構成が正しく、JDK 21がKeycloakの実行に使用されている場合にのみ表示されます。

インストール後、フェデレーションSSSDストアを設定します。

これで、FreeIPA/IdMユーザーと認証情報を使用してKeycloakに対して認証できます。

デフォルトでは、Keycloakは最も一般的なユーザー属性の一部をカバーする基本的なユーザープロファイル構成を提供します。

Keycloakでは、username属性とemail属性の両方が、ユーザーアカウントを識別、認証、およびリンクするためによく使用されるため、特別な処理が施されています。これらの属性については、設定の変更に制限されており、削除することはできません。

次のセクションで説明するように、独自の属性を取り込んだり、利用可能な属性の設定を変更したりして、ニーズに合わせてデフォルト構成を自由に変更できます。

Keycloakでは、ユーザーはさまざまなコンテキストを通じて管理されます。

管理コンテキストを除き、他のすべてのコンテキストは、ユーザーのセルフサービスフローに関連するため、エンドユーザーコンテキストと見なされます。

これらのコンテキストを知ることは、ユーザーを管理する際にユーザープロファイル構成がどこで有効になるかを理解するために重要です。ユーザーが管理されているコンテキストに関係なく、同じユーザープロファイル構成がUIのレンダリングと属性値の検証に使用されます。

次のセクションで説明するように、特定の属性を管理コンテキストからのみ利用可能にし、エンドユーザーに対して完全に無効にすることができます。管理者に特定のユーザー属性へのアクセスを許可せず、エンドユーザーのみに許可する場合も同様です。

デフォルトでは、Keycloakはユーザープロファイル構成で定義された属性のみを認識します。サーバーは、そこで明示的に定義されていない他の属性をすべて無視します。

ユーザーに設定できるユーザー属性と、それらの値がどのように検証されるかについて厳密にすることで、Keycloakはレルムに別の防御壁を追加し、ユーザーに関連付けられた予期しない属性と値を防ぐのに役立ちます。

そうは言っても、ユーザー属性は次のように分類できます。

非管理対象属性はデフォルトで無効になっていますが、さまざまなポリシーを使用してレルムを構成し、サーバーによる処理方法を定義できます。そのためには、左側のメニューのレルム設定をクリックし、一般タブをクリックして、非管理対象属性設定から次のいずれかのオプションを選択します。

これらのポリシーにより、サーバーが非管理対象属性をどのように処理するかをきめ細かく制御できます。管理コンテキストを介してユーザーを管理する場合、非管理対象属性を完全に無効にするか、またはサポートのみにすることを選択できます。

非管理対象属性が（部分的であっても）有効になっている場合、管理コンソールのユーザー詳細UIの属性タブから管理できます。ポリシーが無効に設定されている場合、このタブは使用できません。

セキュリティに関する推奨事項として、可能な限り最も厳格なポリシー（例：無効または管理者は編集可能）に準拠して、エンドユーザーコンテキストを通じてプロファイルを管理する際に、予期しない属性（および値）がユーザーに設定されるのを防ぐようにしてください。有効ポリシーを設定することは避け、エンドユーザーが管理できるすべての属性をユーザープロファイル構成で制御下に定義することを推奨します。

次のセクションで説明するように、属性の対象者を制限して、ユーザーおよび/または管理者が表示または書き込み可能にするかどうかを選択することもできます。

非管理対象属性の場合、最大長は2048文字です。異なる最小長または最大長を指定するには、非管理対象属性を管理対象属性に変更し、lengthバリデーターを追加します。

ユーザープロファイル構成は、レルムごとに管理されます。そのためには、左側のメニューのレルム設定リンクをクリックし、ユーザープロファイルタブをクリックします。

属性サブタブには、すべての管理対象属性のリストがあります。

属性グループサブタブでは、属性グループを管理できます。属性グループを使用すると、ユーザー向けのフォームをレンダリングするときに属性をまとめて表示するように関連付けることができます。

JSONエディターサブタブでは、JSON構成を表示および編集できます。このタブを使用して、現在の構成を取得したり、手動で管理したりできます。このタブで行った変更は、他のタブにも反映され、逆もまた同様です。

次のセクションでは、属性の管理方法について学習します。

属性 サブタブでは、管理対象の属性を作成、編集、および削除できます。

新しい属性を定義し、ユーザープロファイルに関連付けるには、属性リストの上部にある 属性の作成 ボタンをクリックします。

属性を設定する際には、以下の設定を定義できます

属性を作成すると、属性がエンドユーザーに予期せず公開されるのを防ぐために、属性は管理コンテキストからのみ利用可能になります。実際には、エンドユーザーがエンドユーザーコンテキストを介してプロファイルを管理している場合、属性はエンドユーザーにアクセスできなくなります。 パーミッション 設定は、必要に応じていつでも変更できます。

管理対象の属性に対して検証を有効にして、属性値が特定のルールに準拠していることを確認できます。そのためには、属性を管理する際に 検証 設定からバリデーターを追加または削除できます。

検証は、属性への書き込み時にいつでも行われ、値が検証に失敗した場合にUIに表示されるエラーをスローする可能性があります。

セキュリティ上の理由から、ユーザーが編集可能なすべての属性には、ユーザーが入力する値のサイズを制限するための検証が必要です。 length バリデーターが指定されていない場合、Keycloakはデフォルトで最大長を2048文字に設定します。

追加情報をフロントエンドに渡すために、属性を注釈で装飾して、属性のレンダリング方法を指示できます。この機能は、主にKeycloakテーマを拡張して、属性に関連付けられた注釈に基づいてページを動的にレンダリングする場合に役立ちます。

注釈は、たとえば、属性のHTML type の変更 および 属性のDOM表現の変更 に使用されます。これについては、次のセクションで説明します。

注釈は、UIと共有されるキー/値ペアであり、属性に対応するHTML要素のレンダリング方法を変更できます。レルムが使用しているテーマで注釈がサポートされている限り、任意の注釈を属性に設定できます。

属性グループ サブタブでは、属性グループの作成、編集、および削除を行うことができます。属性グループを使用すると、関連する属性のコンテナを定義して、ユーザー向けフォームで一緒にレンダリングされるようにすることができます。

新しいグループを作成するには、属性グループリストの上部にある 属性グループを作成 ボタンをクリックします。

グループを構成するときは、次の設定を定義できます。

ユーザープロファイル構成は、適切に定義された JSON スキーマを使用して保存されます。JSON エディター サブタブをクリックして、ユーザープロファイル構成を直接編集することを選択できます。

JSON スキーマは次のように定義されています。

スキーマは、必要な数の属性とグループをサポートします。

unmanagedAttributePolicy プロパティは、次のいずれかの値を設定することにより、アンマネージド属性ポリシーを定義します。詳細については、マネージド属性とアンマネージド属性の理解 を参照してください。

すべてのユーザープロファイルコンテキスト（管理コンソールを含む）からの UI は、ユーザープロファイル構成に従って動的にレンダリングされます。

デフォルトのレンダリングメカニズムは、次の機能を提供します。

エンドユーザープロファイルが構成に準拠していることを確認するために、管理者は VerifyProfile 必須アクションを使用して、Keycloak に認証するときにユーザーにプロファイルを更新させる場合があります。

有効にすると、VerifyProfile アクションは、ユーザーが認証するときに次の手順を実行します。

VerifyProfile アクションはデフォルトで有効になっています。無効にするには、左側のメニューの 認証 リンクをクリックし、次に 必須アクション タブをクリックします。このタブで、VerifyProfile アクションの 有効 スイッチを使用して無効にします。

属性、属性グループ、およびアノテーションを構成するときに国際化されたメッセージを使用する場合は、メッセージバンドルからのメッセージに変換されるプレースホルダーを使用して、表示名、説明、および値を設定できます。

そのためには、メッセージキーを解決するために、${myAttributeName} などのプレースホルダーを使用できます。ここで、myAttributeName はメッセージバンドル内のメッセージのキーです。詳細については、カスタムテーマにメッセージバンドルを追加する方法に関する サーバー開発者ガイド を参照してください。

ユーザーがすでにパスワードを持っている場合は、パスワードリセットセクションでリセットできます。

ユーザーにパスワードのリセットを要求することもできます。

または、ユーザーにOTPジェネレーターのリセットを要求するメールを送信できます。以下の手順は、ユーザーがすでにOTPクレデンシャルを持っている場合にも適用されます。

この設定を有効にすると、Admin ConsoleのログインページにRegisterリンクが表示されます。

すべてのユーザーに必須のアクションを設定できます。

すべての新規ユーザーの初回ログイン前に必須となるアクションを指定できます。要件は、UsersページのAdd UserボタンまたはログインページのRegisterリンクによって作成されたユーザーに適用されます。

Application initiated actions (AIA) allow client applications to request a user to perform an action on the Keycloak side. Usually, when an OIDC client application wants a user to log in, it redirects that user to the login URL as described in the OIDC section. After login, the user is redirected back to the client application. The user performs the actions that were required by the administrator as described in the previous section and then is immediately redirected back to the application. However, AIA allows the client application to request some required actions from the user during login. This can be done even if the user is already authenticated on the client and has an active SSO session. It is triggered by adding the kc_action parameter to the OIDC login URL with the value containing the requested action. For instance kc_action=UPDATE_PASSWORD parameter.

A user may cancel an application initiated action. In this case the user is redirected back to the client application. The redirect URI will contain the query parameters kc_action_status=cancelled and kc_action with the name of the cancelled action.

So if AIA is used, an example flow is similar to the following

AIAは、パスワードの更新や、OTPやWebAuthnなどの他のクレデンシャルのリセットを要求するために、Keycloakのアカウントコンソールで使用されることに注意してください。

ユーザーを検索して、ユーザーのグループやロールなど、ユーザーに関する詳細情報を表示します。

アプリケーションへのアクセスが不要になったユーザーを削除できます。ユーザーが削除されると、ユーザープロファイルとデータも削除されます。

Admin Consoleでこの機能を有効にすると、エンドユーザーとアプリケーションはアカウントコンソールで自分のアカウントを削除できます。この機能を有効にすると、特定のユーザーにその機能を与えることができます。

適切な権限を持つ管理者は、ユーザーを偽装できます。たとえば、ユーザーがアプリケーションでバグを経験した場合、管理者はユーザーを偽装して問題を調査または再現できます。

レルムでimpersonationロールを持つユーザーは、ユーザーを偽装できます。

どちらの場合も、偽装されたユーザーのアカウントコンソールが表示されます。

デフォルトでは、Keycloak は次のデータを収集します。

Keycloak で収集される情報は高度にカスタマイズ可能です。カスタマイズを行う際には、次のガイドラインが適用されます。