Red Hat Summit5.2. ユーザー属性の管理
Red Hat build of Keycloak では、ユーザーは一連の属性に関連付けられます。これらの属性は、Red Hat build of Keycloak 内でユーザーをより適切に記述および識別するため、またユーザーに関する追加情報をアプリケーションに渡すために使用されます。
ユーザープロファイルは、ユーザー属性とレルム内で管理する方法を表す明確に定義されたスキーマを定義します。ユーザー情報に対する一貫したビューを提供することにより、管理者は属性の管理方法に関するさまざまな側面を制御できるだけでなく、追加の属性をサポートするように Red Hat build of Keycloak を容易に拡張できます。
ユーザープロファイルは、エンドユーザーが管理できる属性 (名、姓、電話番号など) を主に対象としていますが、ユーザーに関連付けるその他のメタデータの管理にも役立ちます。
他の機能の中で、管理者は以下を行うことができます。
- ユーザー属性のスキーマを定義できます。
- コンテキスト情報に基づいて属性が必要なかどうかを定義します (例: ユーザーまたは管理者に必要となる場合、または両方の場合、または要求されるスコープに応じて)。
- ユーザー属性を表示および編集するための特定のパーミッションを定義してください。これにより、一部の属性が表示できないか、3 番目の部分 (管理者を含む) によって変更されない、強力なプライバシー要件に準拠することができます。
- ユーザープロファイルのコンプライアンスを動的に実施して、ユーザー情報が常に、属性に関連付けられたメタデータとルールに準拠します。
- ビルトインバリデーターを利用するか、カスタムレジストリーを書き込むことで、属性ごとに検証ルールを定義します。
- 属性の定義やそれらを手動で変更しなくても、ユーザーがアカウントコンソール内の登録、更新プロファイル、ブローカー、個人情報などと対話するフォームを動的にレンダリングします。
- 管理コンソールのユーザー管理インターフェイスをカスタマイズして、ユーザープロファイルスキーマに基づいて属性を動的にレンダリングできます。
ユーザープロファイルスキーマまたは設定では、属性とそのメタデータを表すために JSON 形式を使用します。管理コンソールから、左側のメニューの Realm Settings をクリックし、そのページの User Profile タブをクリックすることで、設定を管理できます。
次のセクションでは、独自のユーザープロファイルスキーマまたは設定を作成する方法と、属性を管理する方法を説明します。
5.2.1. デフォルト設定について
デフォルトで、Red Hat build of Keycloak は、最も一般的なユーザー属性の一部を含む基本的なユーザープロファイル設定を提供します。
| 名前 | 説明 |
|---|---|
|
| ユーザー名。 |
|
| エンドユーザーが希望するメールアドレス |
|
| エンドユーザーの名 |
|
| エンドユーザーの姓 |
Red Hat build of Keycloak の username 属性と email 属性は、ユーザーアカウントの識別、認証、リンクによく使用されるため、特別に扱われています。これらの属性は、設定の変更のみが可能であり、削除することはできません。
username 属性と email 属性の両方の動作は、レルムの Login 設定に応じて変わります。たとえば、Email as username を変更したり、Edit username 設定を変更したりすると、ユーザープロファイル設定で指定したすべての設定がオーバーライドされます。
次のセクションで説明するように、独自の属性を追加したり、利用可能な属性の設定を変更したりして、ニーズに合わせてデフォルト設定を自由に変更できます。
5.2.2. ユーザープロファイルのコンテキストについて
Red Hat build of Keycloak では、ユーザーは以下のさまざまなコンテキストを通じて管理されます。
- 登録
- プロファイルの更新
- プロファイルの確認 (ブローカーまたはソーシャルプロバイダーを通じて認証する場合)
- アカウントコンソール
- 管理 (管理コンソールや Admin REST API など)
Administrative コンテキストを除く他のすべてのコンテキストは、ユーザーのセルフサービスフローに関連しているため、エンドユーザーコンテキストと見なされます。
これらのコンテキストを知ることは、ユーザーを管理するときにユーザープロファイル設定がどこで有効になるかを理解する上で重要です。ユーザーが管理されているコンテキストに関係なく、UI のレンダリングと属性値の検証には、同じユーザープロファイル設定が使用されます。
次のセクションで説明するように、特定の属性を管理コンテキストからのみ使用できるように制限し、エンドユーザーに対して完全に無効にすることができます。その逆も同様です。管理者に特定のユーザー属性へのアクセスを許可せず、エンドユーザーのみにアクセスを許可する場合は、それを行うことができます。
5.2.3. 管理対象の属性と管理対象外の属性について
デフォルトでは、Red Hat build of Keycloak は、ユーザープロファイル設定で定義された属性のみを認識します。そこで明示的に定義されていない他の属性は無視されます。
Red Hat build of Keycloak は、ユーザーに設定できるユーザー属性とその値の検証方法を厳密に規定することで、レルムに別の防御バリアを追加し、ユーザーに予期しない属性や値が関連付けられるのを防止できます。
そのため、ユーザー属性は次のように分類できます。
- 管理対象: これはユーザープロファイルによって制御される属性です。エンドユーザーと管理者がすべてのユーザープロファイルコンテキストからこの属性を管理できるようにすることを推奨します。この種類の属性は、管理方法と管理のタイミングを完全に制御することを推奨します。
- 管理対象外: これはユーザープロファイルで明示的に定義されない属性であるため、デフォルトでは Red Hat build of Keycloak によって完全に無視されます。
管理対象外の属性はデフォルトでは無効になっていますが、さまざまなポリシーを使用してレルムを設定することで、サーバーによる管理対象外の属性の処理方法を定義できます。これを行うには、左側のメニューで Realm Settings をクリックし、General タブをクリックして、Unmanaged Attributes 設定から次のいずれかのオプションを選択します。
- Disabled: これはデフォルトのポリシーであり、管理対象外の属性がすべてのユーザープロファイルコンテキストで無効になります。
- Enabled: このポリシーは、すべてのユーザープロファイルコンテキストに対して管理対象外の属性を有効にします。
- Admin can view: このポリシーは、管理コンテキストでのみ、管理対象外の属性を読み取り専用として有効にします。
- Admin can edit: このポリシーは、管理コンテキストでのみ、管理対象外の属性の読み取りと書き込みを有効にします。
これらのポリシーを使用すると、サーバーが管理対象外の属性を処理する方法をきめ細かく制御できます。管理コンテキストからユーザーを管理するときに、管理対象外の属性を完全に無効にするか、管理対象外の属性のみをサポートするかを選択できます。
管理対象外の属性が (部分的にでも) 有効になっている場合、User Details UI の Attributes タブにある管理コンソールから属性を管理できます。ポリシーが Disabled に設定されている場合、このタブは使用できません。
セキュリティー上の推奨事項として、エンドユーザーコンテキストからユーザーがプロファイルを管理するときに予期しない属性 (および値) が設定されないように、可能な限り最も厳格なポリシー (例: Disabled または Admin can edit) に準拠するようにしてください。Enabled ポリシーの設定は避け、エンドユーザーが管理できるすべての属性をユーザープロファイル設定で管理できるように定義することを推奨します。
Enabled ポリシーは、以前のバージョンの Red Hat build of Keycloak から移行するレルムを対象としています。カスタムテーマを使用し、独自のカスタムユーザー属性を使用してサーバーを拡張するときに動作が中断するのを防ぐためのものです。
次のセクションで説明するように、ユーザーや管理者が属性を表示または書き込みできるようにするかどうかを選択することで、属性の対象者を制限することもできます。
管理対象外の属性の場合、最大長は 2048 文字です。異なる最小長または最大長を指定するには、管理対象外の属性を管理対象の属性に変更し、length バリデーターを追加します。
Red Hat build of Keycloak はユーザー関連のオブジェクトを内部キャッシュにキャッシュします。属性が長くなるほど、キャッシュが消費するメモリーも多くなります。したがって、長さ属性のサイズを制限することを推奨します。大きなオブジェクトは Red Hat build of Keycloak の外部に保存し、ID または URL で参照することを検討してください。
5.2.4. ユーザープロファイルの管理
ユーザープロファイル設定は、レルムごとに管理されます。これには、左側のメニューで Realm Settings リンクをクリックし、User Profile タブをクリックします。
ユーザープロファイルタブ
Attributes サブタブには、すべての管理対象属性のリストが表示されます。
Attribute Groups サブタブでは、属性グループを管理できます。属性グループを使用すると、ユーザーに表示されるフォームをレンダリングする際に属性を関連付けることができます。
JSON Editor サブタブでは、JSON 設定を表示および編集できます。このタブを使用して、現在の設定を取得したり、手動で管理したりできます。このタブに加えた変更は他のタブに反映されます。その逆も同様です。
次のセクションでは、属性を管理する方法を説明します。
5.2.5. 属性の管理
Attributes サブタブでは、管理対象の属性を作成、編集、削除できます。
新しい属性を定義してユーザープロファイルに関連付けるには、属性リストの上部にある Create attribute ボタンをクリックします。
属性設定
属性の設定時に、以下の設定を定義できます。
- Name
- 属性を一意に識別するために使用される属性の名前。
- Display name
- 属性のユーザーフレンドリーな名前。主にユーザーに表示されるフォームをレンダリングする場合に使用されます。国際化メッセージの使用 もサポートしています。
- Multivalued
- 有効にすると、属性で複数の値がサポートされ、それに応じて UI がレンダリングされ、多くの値を設定できるようになります。この設定を有効にする場合は、値の数にハード制限を設定するバリデーターを必ず追加してください。
- Attribute Group
- 属性が属する属性グループ (ある場合)。
- Enabled when
-
属性を有効または無効にします。
Alwaysに設定すると、どのユーザープロファイルコンテキストからでも属性を使用できるようになります。Scopes are requestedに設定すると、ユーザーに代わって動作するクライアントが 1 つ以上のスコープのセットを要求している場合にのみ、この属性を使用できます。このオプションを使用すると、要求されているクライアントスコープに応じて特定の属性を動的に適用できます。管理コンソールの場合、スコープは評価されず、属性は常に有効です。これは、スコープによる属性のフィルタリングがエンドユーザー認証フローの実行時にしか機能しないためです。 - Required
-
属性を必須とマークするための条件を設定します。無効にした場合、属性は任意になります。有効にすると、ユーザープロファイルコンテキストに応じて属性を必須としてマークする
Required forを設定して、エンドユーザー (エンドユーザーコンテキストで) または管理者 (管理コンテキストで)、あるいはその両方に対して属性を必須にすることができます。また、Required whenを設定し、1 つ以上のクライアントスコープのセットが要求された場合にのみ属性を必須とマークすることもできます。Alwaysに設定すると、すべてのユーザープロファイルコンテキストで属性が必須になります。Scopes are requestedに設定すると、ユーザーに代わって動作するクライアントが 1 つ以上のスコープのセットを要求している場合にのみ、この属性が必須になります。アカウントおよび管理コンソールの場合、スコープは評価されず、属性は必須になりません。これは、スコープによる属性のフィルタリングが認証フローの実行時にしか機能しないためです。 - Permission
-
このセクションでは、エンドユーザーコンテキストまたは管理コンテキストから属性が管理されている場合の読み取りおよび書き込み権限を定義できます。
Who can edit設定は、エンドユーザーコンテキストからのUserによる書き込みや、管理コンテキストからのAdminによる書き込みを許可するように属性をマークします。Who can view設定は、エンドユーザーコンテキストからのUserによる読み取りや、管理コンテキストからのAdminによる読み取りのみを許可するように属性をマークします。 - Validation
- このセクションでは、属性値を管理するときに実行する検証を定義できます。Red Hat build of Keycloak では、選択可能なビルトインバリデーターのセットが提供されており、独自に追加することも可能です。詳細は、属性の検証 セクションを参照してください。
- Annotation
- このセクションでは、アノテーションを属性に関連付けることができます。アノテーションは、レンダリングの目的で追加のメタデータをフロントエンドに渡すのに役立ちます。詳細は、UI アノテーションの定義 セクションを参照してください。
属性を作成すると、属性が予期せずエンドユーザーに公開されるのを避けるために、その属性は管理コンテキストからのみ使用可能になります。実際、エンドユーザーがエンドユーザーコンテキストからプロファイルを管理しているときに、その属性にアクセスすることはできません。Permissions 設定は、必要に応じていつでも変更できます。
5.2.6. 属性の検証
管理対象の属性に対する検証を有効にして、属性値が特定のルールに準拠していることを確認できます。そのためには、属性を管理するときに、Validations 設定からバリデーターを追加または削除できます。
属性の検証
検証は、属性への書き込み時に随時実行されます。値が検証に失敗したときに、エラーを出力して UI に表示できます。
セキュリティー上の理由から、ユーザーが編集可能なすべての属性に、ユーザーが入力する値のサイズを制限する検証を指定する必要があります。length バリデーターが指定されていない場合、Red Hat build of Keycloak ではデフォルトで最大長が 2048 文字に設定されます。
5.2.6.1. ビルトインバリデーター
Red Hat build of Keycloak には、選択可能なビルトインバリデーターがいくつか用意されています。また、Validator SPI を拡張して独自のバリデーターを提供することもできます。
以下に、すべてのビルトインバリデーターのリストを示します。
| 名前 | 説明 | 設定 |
|---|---|---|
| length | 最小と最大長に基づいて文字列値の長さを確認します。 | min: 許容される最小長を定義する整数。 max: 許容される最大長を定義する整数。 trim-disabled: 検証前に値がトリミングされるかどうかを定義するブール値。 |
| integer | 値が整数であり、下限または上限の範囲内にあるかどうかを確認します。範囲が定義されていない場合、バリデーターは、値が有効な数字のみを確認します。 | Min: 小さい範囲を定義する整数。 max: 上限を定義する整数。 |
| double | 値が二重で、下層または上位の範囲内であるかどうかを確認します。範囲が定義されていない場合、バリデーターは、値が有効な数字のみを確認します。 | Min: 小さい範囲を定義する整数。 max: 上限を定義する整数。 |
| uri | 値が有効な URI かどうかを確認します。 | なし |
| pattern | 値が特定の RegEx パターンと一致するかどうかを確認します。 | パターン: 値の検証時に使用する RegEx パターン。 error-message: i18n バンドルのエラーメッセージのキー。設定されていない場合には、汎用メッセージが使用されます。 |
| | 値が有効なメールアドレスの形式かどうかを確認します。 | max-local-length: メールアドレスのローカル部分の最大長を定義する整数。仕様に従ってデフォルトで 64 に設定されます。 |
| local-date | レルムまたはユーザーロケールに基づいて、値が有効な形式かどうかを確認します。 | なし |
| iso-date | 値が ISO 8601 に基づく有効な形式であるかどうかを確認します。このバリデーターは、html5-date 入力タイプを使用した入力で使用できます。 | なし |
| person-name-prohibited-characters | 値がスクリプトインジェクションなどの攻撃にもう 1 つのバリアとして有効な人名であるかを確認します。検証は、デフォルト RegEx パターンをベースとしています。このパターンでは、文字が人名では一般的ではありません。 | error-message: i18n バンドルのエラーメッセージのキー。設定されていない場合には、汎用メッセージが使用されます。 |
| username-prohibited-characters |
値がスクリプトインジェクションなどの攻撃のためにもう 1 つのバリアとして有効なユーザー名であるかを確認します。検証は、ユーザー名に共通の文字をブロックするデフォルトの RegEx パターンに基づいています。 | error-message: i18n バンドルのエラーメッセージのキー。設定されていない場合には、汎用メッセージが使用されます。 |
| options | 値が許可された値の定義されたセットからのものであるかどうかを確認してください。選択フィールドと複数選択フィールドから入力された値を検証するのに便利です。 | options: 許可された値を含む文字列の配列。 |
| up-username-not-idn-homograph | このフィールドには、ラテン文字と一般的な Unicode 文字のみを含めることができます。IDN ホモグラフ攻撃の対象となる可能性のあるフィールド (ユーザー名など) に役立ちます。 | error-message: i18n バンドルのエラーメッセージのキー。設定されていない場合には、汎用メッセージが使用されます。 |
| multivalued | 複数値属性のサイズを検証します。 | min: 属性値の最小許容数を定義する整数。 max: 属性値の最大許容数を定義する整数。 |
5.2.7. UI アノテーションの定義
フロントエンドに追加情報を渡すには、属性をレンダリングする方法を決定するアノテーションで属性を切り分けることができます。この機能は主に、Red Hat build of Keycloak テーマを拡張して、属性に関連付けられたアノテーションに基づきページを動的にレンダリングする場合に役立ちます。
アノテーションは、たとえば、次のセクションで説明するように、属性の HTML type を変更 したり、属性の DOM 表現を変更 したりするために使用されます。
属性アノテーション
アノテーションは、キーと値のペアであり、属性に対応する HTML 要素のレンダリング方法を変更できるように UI と共有されます。レルムで使用されているテーマによってアノテーションがサポートされている限り、任意のアノテーションを属性に設定できます。
唯一の制限として、キーに kc 接頭辞を使用するアノテーションの使用を避ける必要があります。この接頭辞を使用するアノテーションは、Red Hat build of Keycloak 用に予約されているためです。
5.2.7.1. ビルトインアノテーション
Red Hat build of Keycloak のビルトインテーマでは、次のアノテーションがサポートされています。
| 名前 | 説明 |
|---|---|
| inputType | フォーム入力フィールドのタイプ。利用可能なタイプは以下の表で説明されています。 |
| inputHelperTextBefore |
入力フィールドの前 (上) に表示されるヘルパーテキスト。ここでは、直接のテキストまたは国際化パターン ( |
| inputHelperTextAfter |
入力フィールドの後にレンダリングされるヘルパーテキスト。ここでは、直接のテキストまたは国際化パターン ( |
| inputOptionsFromValidation | タイプを選択および複数選択するためのアノテーション。入力オプションの取得元となるカスタム属性検証のオプション名。詳しい説明 は、下記を参照してください。 |
| inputOptionLabelsI18nPrefix | タイプを選択および複数選択するためのアノテーション。UI でオプションをレンダリングする国際化キー接頭辞。詳しい説明 は、下記を参照してください。 |
| inputOptionLabels | タイプを選択および複数選択するためのアノテーション。オプションの UI ラベルを定義するためのオプションのマップ (直接または国際化を使用)。詳しい説明 は、下記を参照してください。 |
| inputTypePlaceholder |
フィールドに適用される HTML 入力 |
| inputTypeSize |
フィールドに適用される HTML 入力 |
| inputTypeCols |
フィールドに適用される HTML 入力 |
| inputTypeRows |
フィールドに適用される HTML 入力 |
| inputTypePattern |
クライアント側の検証を提供するフィールドに適用される HTML 入力 |
| inputTypeMaxLength |
クライアント側の検証を提供するフィールドに適用される HTML 入力 |
| inputTypeMinLength |
クライアント側の検証を提供するフィールドに適用される HTML 入力 |
| inputTypeMax |
クライアント側の検証を提供するフィールドに適用される HTML 入力 |
| inputTypeMin |
クライアント側の検証を提供するフィールドに適用される HTML 入力 |
| inputTypeStep |
フィールドに適用される HTML 入力 |
| Number Format |
設定すると、指定の形式に基づいて値をフォーマットするための |
| Number UnFormat |
設定すると、フォームを送信する前に、指定の形式に基づいて値をフォーマットするための |
フィールドタイプは、HTML フォームフィールドタグとそれに適用される属性を使用します。フィールドタイプは、HTML 仕様とブラウザーサポートに基づいて動作します。
ビジュアルレンダリングは、使用するテーマに適用されている css スタイルにも依存します。
5.2.7.2. 属性の HTML type の変更
inputType アノテーションを設定することで、HTML5 入力要素の type を変更できます。利用可能なタイプは次のとおりです。
| 名前 | 説明 | 使用される HTML タグ |
|---|---|---|
| text | 単一行のテキスト入力。 | 入力 (input) |
| textarea | 複数の行テキスト入力。 | textarea |
| select | 一般的な単一の選択入力。オプションの設定方法 については、以下を参照してください。 | select |
| select-radiobuttons | ラジオボタンをグループ化して入力を 1 つ選択します。オプションの設定方法 については、以下を参照してください。 | 入力グループ |
| 複数選択 | 一般的な複数選択入力。オプションの設定方法 については、以下を参照してください。 | select |
| multiselect-checkboxes | チェックボックスのグループで入力を複数選択します。オプションの設定方法 については、以下を参照してください。 | 入力グループ |
| html5-email | HTML 5 仕様に基づくメールアドレスの単一行のテキスト入力。 | 入力 (input) |
| html5-tel | HTML 5 仕様に基づく電話番号の単一行のテキスト入力。 | 入力 (input) |
| html5-url | HTML 5 仕様に基づく URL の単一行のテキスト入力。 | 入力 (input) |
| html5-number |
HTML 5 仕様に基づく数値 ( | 入力 (input) |
| html5-range | HTML 5 仕様に基づいて入力した数字のスライダー。 | 入力 (input) |
| html5-datetime-local | HTML 5 仕様に基づく日付入力。 | 入力 (input) |
| html5-date | HTML 5 仕様に基づく日付入力。 | 入力 (input) |
| html5-month | HTML 5 仕様に基づいた月入力。 | 入力 (input) |
| html5-week | HTML 5 仕様に基づく週入力。 | 入力 (input) |
| html5-time | HTML 5 仕様に基づく時間入力。 | 入力 (input) |
5.2.7.3. select フィールドおよび multiselect フィールドのオプションの定義
選択フィールドと複数選択フィールドのオプションは、属性に適用された検証から取得され、UI に表示される検証とフィールドオプションが常に一貫していることを確認します。デフォルトでは、オプションはビルトイン options の検証から取得されます。
さまざまな方法を使用して、選択オプションと複数選択オプションに人間が判読できる適切なラベルを提供できます。最も単純なケースでは、属性値が UI ラベルと同じである場合です。この場合、追加の設定は必要ありません。
オプションの値は UI ラベルと同じです。
属性値が UI に適さない ID の種類である場合、inputOptionLabelsI18nPrefix アノテーションによって提供される単純な国際化サポートを使用できます。これは国際化キーの接頭辞を定義します。オプション値はこの接頭辞に追加されるドットになります。
i18n キー接頭辞を使用した UI ラベルの簡単な国際化
オプション値のローカライズされた UI ラベルテキストは、一般的なローカリゼーションメカニズムを使用して、userprofile.jobtitle.sweng キーおよび userprofile.jobtitle.swarch キーで提供する必要があります。
inputOptionLabels アノテーションを使用して、個別のオプションのラベルを指定することもできます。このアノテーションには、オプションのラベルのマップを含めます。マップ内のキーは、オプションの値 (検証で定義する値) です。マップ内の値は、そのオプションの UI ラベルテキスト自体またはその国際化パターン (${i18n.key} など) です。
User Profile JSON Editor を使用して map を inputOptionLabels アノテーションの値として入力する必要があります。
国際化なしで各オプションの直接入力されたラベルの例:
"attributes": [
<...
{
"name": "jobTitle",
"validations": {
"options": {
"options":[
"sweng",
"swarch"
]
}
},
"annotations": {
"inputType": "select",
"inputOptionLabels": {
"sweng": "Software Engineer",
"swarch": "Software Architect"
}
}
}
...
]個別オプションの国際化されたラベルの例:
"attributes": [
...
{
"name": "jobTitle",
"validations": {
"options": {
"options":[
"sweng",
"swarch"
]
}
},
"annotations": {
"inputType": "select-radiobuttons",
"inputOptionLabels": {
"sweng": "${jobtitle.swengineer}",
"swarch": "${jobtitle.swarchitect}"
}
}
}
...
]
ローカライズされたテキストは、一般的なローカリゼーションメカニズムを使用して、jobtitle.swengineer キーと jobtitle.swarchitect キーで提供する必要があります。
inputOptionsFromValidation 属性アノテーションのおかげで、カスタムバリデーターを使用してオプションを提供できます。この検証には、オプションの配列を提供する options 設定が必要です。国際化は、ビルトインの options 検証によって提供されるオプションの場合と同じように機能します。
カスタムバリデーターが提供するオプション
5.2.7.4. 属性の DOM 表現の変更
kc 接頭辞付きのアノテーションを設定することで、追加のクライアント側の動作を有効にできます。この種類のアノテーションは、属性の対応する要素内の data- という接頭辞が付いた HTML 属性に変換されます。同じ名前のスクリプトが動的ページに読み込まれるため、カスタムの data- 属性に基づいて DOM から要素を選択し、それに応じて DOM 表現を変更して要素を装飾することができます。
たとえば、属性に kcMyCustomValidation アノテーションを追加すると、HTML 属性 data-kcMyCustomValidation が属性の対応する HTML 要素に追加され、<THEME TYPE>/resources/js/kcMyCustomValidation.js にあるカスタムテーマから JavaScript モジュールがロードされます。カスタム JavaScript モジュールをテーマにデプロイする方法の詳細は、サーバー開発者ガイド を参照してください。
JavaScript モジュールは任意のコードを実行して、DOM と各属性に対してレンダリングされる要素をカスタマイズできます。そのためには、次のように userProfile.js モジュールを使用して、カスタムアノテーションのアノテーション記述子を登録します。
import { registerElementAnnotatedBy } from "./userProfile.js";
registerElementAnnotatedBy({
name: 'kcMyCustomValidation',
onAdd(element) {
var listener = function (event) {
// do something on keyup
};
element.addEventListener("keyup", listener);
// returns a cleanup function to remove the event listener
return () => element.removeEventListener("keyup", listener);
}
});
registerElementAnnotatedBy は、アノテーション記述子を登録するメソッドです。記述子は、アノテーション名を参照する name と onAdd 関数を持つオブジェクトです。ページがレンダリングされるか、アノテーション付きの属性が DOM に追加されるたびに、onAdd 関数が呼び出され、要素の動作をカスタマイズできるようになります。
onAdd 関数は、クリーンアップを実行する関数を返すこともできます。たとえば、要素にイベントリスナーを追加する場合、要素が DOM から削除されたときにイベントリスナーを削除することもできます。
userProfile.js がニーズに合わない場合は、任意の JavaScript コードを使用することもできます。
document.querySelectorAll(`[data-kcMyCustomValidation]`).forEach((element) => {
var listener = function (evt) {
// do something on keyup
};
element.addEventListener("keyup", listener);
});5.2.8. 属性グループの管理
Attribute Groups サブタブで、属性グループを作成、編集、削除できます。属性グループを使用すると、相関属性のコンテナーを定義でき、ユーザーに表示されるフォームで一緒にレンダリングできます。
属性グループリスト
属性にバインドされる属性グループを削除できません。そのため、最初に属性を更新してバインディングを削除する必要があります。
新しいグループを作成するには、属性グループのリストの上部にある属性グループの作成 ボタンをクリックします。
属性グループ設定
グループを設定する際に、以下の設定を定義できます。
- 名前
- 属性を一意に識別するために使用される属性の名前。
- Display name
- 属性のユーザーフレンドリーな名前。主にユーザーに表示されるフォームをレンダリングする場合に使用されます。国際化メッセージの使用 もサポートしています。
- 説明の表示
- ユーザーに表示されるフォームをレンダリングする際にツールチップとして表示されるユーザーフレンドリーなテキストです。国際化メッセージの使用 もサポートしています。
- アノテーション
- このセクションでは、アノテーションを属性に関連付けることができます。アノテーションは、レンダリングの目的で追加のメタデータをフロントエンドに渡すのに役立ちます。
5.2.9. JSON 設定の使用
ユーザープロファイル設定は、明確に定義された JSON スキーマを使用して保存されます。JSON Editor サブタブで直接ユーザープロファイル設定の編集を選択できます。
JSON 設定
JSON スキーマは以下のように定義されます。
{
"unmanagedAttributePolicy": "DISABLED",
"attributes": [
{
"name": "myattribute",
"multivalued": false,
"displayName": "My Attribute",
"group": "personalInfo",
"required": {
"roles": [ "user", "admin" ],
"scopes": [ "foo", "bar" ]
},
"permissions": {
"view": [ "admin", "user" ],
"edit": [ "admin", "user" ]
},
"validations": {
"email": {
"max-local-length": 64
},
"length": {
"max": 255
}
},
"annotations": {
"myannotation": "myannotation-value"
}
}
],
"groups": [
{
"name": "personalInfo",
"displayHeader": "Personal Information",
"annotations": {
"foo": ["foo-value"],
"bar": ["bar-value"]
}
}
]
}このスキーマでは、属性とグループを必要な数だけ使用できます。
unmanagedAttributePolicy プロパティーは、次のいずれかの値を設定して、管理対象外の属性のポリシーを定義します。詳細は、管理対象の属性と管理対象外の属性について を参照してください。
-
DISABLED -
ENABLED -
ADMIN_VIEW -
ADMIN_EDIT
5.2.9.1. 属性スキーマ
属性ごとに、name、オプションで required、permission、および annotations 設定を定義する必要があります。
required プロパティーは、属性が必須かどうかを定義します。Red Hat build of Keycloak を使用すると、さまざまな条件に基づいて必要に応じて属性を設定できます。
required プロパティーが空のオブジェクトとして定義されている場合、属性は常に必須になります。
{
"attributes": [
{
"name": "myattribute",
"required": {}
]
}一方、ユーザーか管理者、もしくは両方に必要な属性の作成を選択できます。また、ユーザーが Red Hat build of Keycloak で認証している際に、特定のスコープが要求される場合にのみ属性にマークを付けることができます。
ユーザーや管理者の必要に応じて属性にマークを付けるには、roles プロパティーを以下のように設定します。
{
"attributes": [
{
"name": "myattribute",
"required": {
"roles": ["user"]
}
]
}
roles プロパティーは、user または admin によって属性が必要であるかどうかによって、値がユーザーまたは admin のいずれかである配列を想定します。
同様に、ユーザーの認証時に 1 つ以上のスコープのセットがクライアントによって要求される場合に、属性の作成を選択できます。そのため、以下のように scopes プロパティーを使用できます。
{
"attributes": [
{
"name": "myattribute",
"required": {
"scopes": ["foo"]
}
]
}
scopes プロパティーは、クライアントスコープを表す任意の文字列を持つことができます。
属性レベルの permissions プロパティーを使用すると、属性への読み取りと書き込みのパーミッションを定義できます。パーミッションは、ユーザー、管理者、またはその両方の属性に対してこれらの操作を実行するかどうかに基づいて設定されます。
{
"attributes": [
{
"name": "myattribute",
"permissions": {
"view": ["admin"],
"edit": ["user"]
}
]
}
view プロパティーと edit プロパティーはいずれも、user または admin が表示可能または管理者が管理者が編集できるかによって、値がユーザーまたは admin のいずれかであることを想定します。
edit パーミッションが付与されると、view パーミッションは暗黙的に付与されます。
属性レベルの annotation プロパティーを使用して、追加のメタデータを属性に関連付けることができます。アノテーションは、主に、ユーザープロファイル設定に基づいてユーザー属性のレンダリングに属性に関する追加情報を渡す場合に有用です。各アノテーションはキー/値のペアです。
{
"attributes": [
{
"name": "myattribute",
"annotations": {
"foo": ["foo-value"],
"bar": ["bar-value"]
}
]
}5.2.9.2. 属性グループスキーマ
各属性グループに対して、name と、必要に応じて annotations 設定を定義してください。
属性レベルの annotation プロパティーを使用して、追加のメタデータを属性に関連付けることができます。アノテーションは、主に、ユーザープロファイル設定に基づいてユーザー属性のレンダリングに属性に関する追加情報を渡す場合に有用です。各アノテーションはキー/値のペアです。
5.2.10. UI のレンダリング方法のカスタマイズ
ユーザープロファイルコンテキスト (管理コンソールを含む) の UI は、すべてユーザープロファイル設定に応じて動的にレンダリングされます。
デフォルトのレンダリングメカニズムは、次の機能を提供します。
- 属性に設定された権限に基づいてフィールドを表示または非表示にします。
- 属性に設定された制約に基づいて、必須フィールドのマーカーをレンダリングします。
- 属性に設定されているフィールド入力タイプ (テキスト、日付、数値、選択、複数選択) を変更します。
- 属性に設定された権限に応じて、フィールドを読み取り専用とマークします。
- 属性に設定された順序に応じてフィールドを順序付けます。
- 同じ属性グループに属するフィールドをグループ化します。
- 同じ属性グループに属するフィールドを動的にグループ化します。
5.2.10.1. 順序の属性
属性の順序は、属性リストページで属性行をドラッグアンドドロップして設定します。
属性の順序付け
このページに設定した順番は、フィールドが動的形式でレンダリングされると考慮されます。
5.2.10.2. 属性のグループ化
動的フォームがレンダリングされるとき、同じ属性グループに属する属性のグループ化が試行されます。
動的更新プロファイルフォーム
属性が属性グループにリンクされている場合、属性の順番も同じグループ内の属性が一緒に閉じられるようにすることが重要になります。それ以外の場合は、グループ内の属性に連続的な順序がない場合、同じグループヘッダーが動的形式で複数回レンダリングされる可能性があります。
5.2.11. プログレッシブプロファイリングの有効化
エンドユーザープロファイルを設定に準拠させるために、管理者は VerifyProfile 必須アクションを使用して、ユーザーが Red Hat build of Keycloak に認証するときに最終的にプロファイルの更新を強制することができます。
VerifyProfile アクションは UpdateProfile アクションに似ています。ただし、ユーザープロファイルが提供するすべての機能を活用して、ユーザープロファイルの設定により自動的にコンプライアンスが強制されます。
有効にすると、ユーザー認証時に VerifyProfile アクションは以下の手順を実行します。
- ユーザープロファイルが、レルムに設定されたユーザープロファイル設定に完全準拠しているかどうかを確認します。つまり、検証を実行し、すべての検証が成功することを確認します。
- そうでない場合には、認証中に追加のステップを実行して、ユーザーが不足している属性や無効な属性を更新できるようにします。
- ユーザープロファイルが設定に準拠する場合は、追加のステップが実行されず、ユーザーは認証プロセスを続行します。
VerifyProfile アクションはデフォルトで有効になっています。無効にするには、左側のメニューの Authentication リンクをクリックし、Required Actions タブをクリックします。このタブで、VerifyProfile アクションの Enabled スイッチを使用して無効にします。
VerifyProfile の必須アクションの登録
5.2.12. 国際化されたメッセージの使用
属性、属性グループ、アノテーションを設定するときに国際化されたメッセージを使用する場合は、メッセージバンドルのメッセージに変換するプレースホルダーを使用して、表示名、説明、値を設定できます。
そのためには、プレースホルダーを使用して、${myAttributeName} などのメッセージキーを解決します。myAttributeName は、メッセージバンドル内のメッセージのキーです。カスタムテーマにメッセージバンドルを追加する方法の詳細は、サーバー開発者ガイド を参照してください。
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}