第2章 移行の変更
2.1. ユーザープロファイルの変更
2.1.1. ユーザープロファイルがデフォルトで有効
ユーザープロファイル機能がデフォルトで有効になりました。ユーザープロファイルが有効であると想定されるため、declarative-user-profile 機能が使用できなくなりました。したがって、User Profile Enabled スイッチが Realm Settings から削除され、Unmanaged attributes に置き換えられました。以前のバージョンから移行する場合、動作は次のようになります。
- User Profile Enabled が ON に設定されているデプロイメントの場合、アップグレード後に Unmanaged attributes が OFF に設定されます。その結果、ユーザープロファイルによって明示的にサポートされているユーザー属性のみが許可されます。
-
User Profile Enabled が OFF (
declarative-user-profile機能が無効なデプロイメントのデフォルト設定。この機能はデフォルトで無効でした) に設定されているデプロイメントの場合、アップグレード後に Unmanaged attributes が ON に設定されます。そのため、動作は、ユーザープロファイルが無効になっている以前のバージョンと基本的に同じです。Attributes タブは、管理コンソールのユーザー詳細部分に引き続き存在します。また、特定のカスタムテーマがサポートしている限り、ユーザーが登録ページやプロファイル更新ページなどの UI ページを通じて任意の属性を設定できるようになりました。カスタムテーマも以前と同じように動作します。ただし、ユーザープロファイルを使用するようにテーマを更新し、カスタム属性を追加する必要があったカスタムテーマを削除することを検討してください。テーマについては後続のセクションを参照してください。また、Unmanaged attributes を OFF に切り替えるか、このスイッチを管理者に対してのみ有効にして、管理対象の属性を主に使用することを検討してください。
Unmanaged attributes の詳細は、ユーザープロファイルのドキュメント を参照してください。
2.1.2. デフォルトの検証
デフォルトのユーザープロファイル設定には、基本的な定義済みフィールドに対するデフォルトの一連の検証が付属しています。これらの検証は、declarative-user-profile 機能がデフォルトで無効になっていた以前のバージョンには存在しませんでした。下位互換性による問題がある場合は、必要に応じてデフォルトのバリデーターを変更できます。デフォルトのバリデーターは次のとおりです。
-
username、email、firstName、lastName属性の最大長は 255 文字です。これらの検証は、最大長が 255 文字のフィールドのUSER_ENTITYテーブルに対するデータベース制約のため、以前のバージョンでも間接的に存在していました。ただし、ユーザーのストレージプロバイダーを使用する場合は、より長い値を使用できる可能性があります。 -
username属性の最小長は 3 文字です。また、ユーザー名には、username-prohibited-charactersとup-username-not-idn-homographのバリデーターがデフォルトで備わっています。これは以前のバージョンには存在しなかったものです。これらの属性の詳細は、ユーザープロファイルドキュメントの検証セクション を参照してください。レルムスイッチのEdit usernameが有効になっていない限り、ユーザー名はデフォルトでは編集できないことに注意してください。この変更により、既存のユーザーはユーザー名が正しくなくても引き続き機能し、ユーザー名の更新が強制されなくなります。一方、新しいユーザーは、管理 REST API によって登録時または作成時に正しいユーザー名を使用するように強制されます。 -
firstName属性とlastName属性には、person-name-prohibited-charactersバリデーターがあります。これは以前のバージョンには存在しなかったものです。これらの属性の詳細は、ユーザープロファイルドキュメントの検証セクション を参照してください。デフォルトでは名と姓の両方が編集可能であることに注意してください。そのため、以前のバージョンで正しくない名/姓を使用していたユーザーは、ユーザープロファイルを更新するときにそれらを更新する必要があります。
2.1.3. 不自然な文字を含むユーザー属性名
以前のバージョンでは、some:attribute や some/attribute などの属性名を使用してユーザーを作成できました。ユーザープロファイル設定では、このような不自然な名前の属性を作成することを意図的に禁止しています。そのため、レルムに対して Unmanaged attributes を設定し、(理想的には) 管理者または (本当に必要な場合) エンドユーザーに対して管理対象外の属性を有効にする必要がある場合があります。ただし、このような属性名の使用は回避することを強く推奨します。
2.1.4. 必須アクションのプロファイル検証がデフォルトで有効
新しいレルムでは、必須アクション verify-profile がデフォルトで有効になっています。ただし、以前のバージョンから移行した場合、既存レルムの verify-profile アクションの状態は、以前と同じになります。以前のバージョンではデフォルトで無効であったため、通常は無効になります。この必須アクションの詳細は、ユーザープロファイルのドキュメント を参照してください。
2.1.5. ユーザープロファイルとレルムに基づいてページをレンダリングする Freemarker テンプレートの変更
このリリースでは、次のテンプレートが更新され、レルムに設定されたユーザープロファイル設定に基づいて属性を動的にレンダリングできるようになりました。
-
login-update-profile.ftl -
register.ftl -
update-email.ftl
これらのテンプレートは、それぞれ、更新プロファイル (ユーザーに対して必須アクション Update Profile が有効になっている場合)、登録、メール更新 (UPDATE_EMAIL 機能が有効になっている場合) ページのレンダリングを担当します。
カスタムテーマを使用してこれらのテンプレートを変更すれば、コンテンツのみが更新されるため、テンプレートが期待どおりに動作します。ただし、宣言型ユーザープロファイル を設定する方法を確認し、可能であればこの機能によって提供されるすべての機能を使用して組み込みテンプレートの変更を回避することを推奨します。
また、このリリースでは、同じフローのページをレンダリングするために declarative-user-profile 機能によって使用されるテンプレートが不要になったため、削除されました。
-
update-user-profile.ftl -
register-user-profile.ftl
以前のリリースで、上記のテンプレートをカスタマイズして declarative-user-profile 機能を使用していた場合は、それに応じて login-update-profile.ftl と register.ftl を更新してください。
2.1.6. ブローカー経由で初めてログインしたときのプロファイル更新ページ用の新しい Freemarker テンプレート
このリリースでは、ユーザーが idp-review-user-profile.ftl テンプレートを使用して初めてブローカー経由で認証するときに、サーバーが更新プロファイルページをレンダリングします。
以前のリリースでは、最初のブローカーログインフロー中にプロファイルを更新するために使用されたテンプレートは login-update-profile.ftl でした。これは、ユーザーがレルムに認証するときにプロファイルを更新するために使用されるものと同じでした。
同じテンプレートを共有するのではなく、各フローに個別のテンプレートを使用すると、どのフローにテンプレートが使用されるかがより明確に区別されます。ただし、特定のフローのページにのみ影響する予期しない変更や動作が発生する可能性があります。
ブローカー経由の認証時にユーザーがプロファイルを更新する方法をカスタマイズするために login-update-profile.ftl テンプレートをカスタマイズした場合は、変更内容を新しいテンプレートに必ず移してください。
