6.13. 以前のユーザーフェデレーション SPI からの移行
本章では、以前の (すでに廃止された)User Federation SPI を使用してプロバイダーを実装している場合のみを対象としています。
Keycloak バージョン 2.4.0 以前のバージョンでは、User Federation SPI がありました。Red Hat Single Sign-On バージョン 7.0 はサポート対象外ですが、この以前の SPI も使用できます。この以前の User Federation SPI は、Keycloak バージョン 2.5.0 および Red Hat Single Sign-On バージョン 7.1 から削除されました。ただし、本章では、この SPI でプロバイダーを作成している場合の移植に使用できるストラテジーについて説明します。
6.13.1. インポートと非インポート
以前の User Federation SPI は、Red Hat build of Keycloak のデータベースでユーザーのローカルコピーを作成し、情報を外部ストアからローカルコピーにインポートする必要がありました。ただし、要件ではなくなりました。以前のプロバイダーもそのままの状態で移植できますが、インポートなしのストラテジーの方が適しているかどうかを検討する必要があります。
インポートストラテジーの利点:
- 基本的に、Red Hat build of Keycloak は外部ストアの永続ユーザーキャッシュになります。ユーザーがインポートされると、外部ストアに到達できなくなるため、負荷がなくなります。
- 公式ユーザーストアとして Red Hat build of Keycloak に移行し、以前の外部ストアを非推奨にする場合は、アプリケーションを徐々に移行して Red Hat build of Keycloak を使用できます。すべてのアプリケーションが移行されたら、インポートされたユーザーのリンクを解除し、古いレガシー外部ストアを破棄します。
インポートストラテジーの使用には、いくつかの明確な欠点があります。
- 初めてユーザーを検索するには、Red Hat build of Keycloak データベースを複数回更新する必要があります。これを実行すると、負荷がかかってパフォーマンスが大幅に低下し、Red Hat build of Keycloak データベースに大きな負担がかかる可能性があります。ユーザーフェデレーションされたストレージアプローチは、必要に応じて追加のデータのみを保存し、外部ストアの機能によっては使用されない可能性があります。
- このインポート方法では、ローカルの Red Hat build of Keycloak ストレージと外部ストレージを同期する必要があります。User Storage SPI には同期をサポートするために実装できる機能インターフェイスがありますが、この操作はすぐに面倒で複雑になる可能性があります。
6.13.2. UserFederationProvider と UserStorageProvider
最初に、UserFederationProvider
が完全なインターフェイスであったことに留意してください。このインターフェイスにすべてのメソッドを実装しました。ただし、UserStorageProvider
は、このインターフェイスを、必要に応じて実装する複数の機能インターフェイスに分割します。
UserFederationProvider.getUserByUsername()
および getUserByEmail()
には、新しい SPI に完全に同等のものが含まれます。この 2 つの違いは、インポートの方法です。インポートストラテジーを続行する場合は、KeycloakSession.userStorage().addUser()
を呼び出してユーザーをローカルに作成しなくなりました。代わりに KeycloakSession.userLocalStorage().addUser()
を呼び出します。userStorage()
メソッドがなくなりました。
UserFederationProvider.validateAndProxy()
メソッドは任意の機能インターフェイス ImportedUserValidation
に移動しました。以前のプロバイダーをそのまま移植する場合は、このインターフェイスを実装する必要があります。また、以前の SPI では、ローカルユーザーがキャッシュにある場合でも、ユーザーがアクセスされたたびにこのメソッドが呼び出されていました。このメソッドは、後の SPI では、ローカルユーザーがローカルストレージからロードされる場合にのみ呼び出されます。ローカルユーザーがキャッシュされていると、ImportedUserValidation.validate()
メソッドは呼び出されません。
UserFederationProvider.isValid()
メソッドは、後続の SPI に存在しなくなりました。
UserFederationProvider
のメソッド synchronizeRegistrations()
、registerUser()
、および removeUser()
が UserRegistrationProvider
機能インターフェイスに移動しました。プロバイダーがユーザーの作成や削除をサポートしていない場合は、この新しいインターフェイスを実装する必要はありません。以前のプロバイダーが新規ユーザー登録のサポートを切り替える場合は、これが新しい SPI でサポートされ、プロバイダーがユーザーの追加をサポートしていない場合は UserRegistrationProvider.addUser()
から Null
を返します。
認証情報を中心とする以前の UserFederationProvider
メソッドは、CredentialInputValidator
インターフェイスおよび CredentialInputUpdater
インターフェイスにカプセル化されるようになりました。また、認証情報の検証または更新をサポートしているかどうかに応じて実装することもできます。認証情報管理は、以前は UserModel
メソッドに存在していました。これらは CredentialInputValidator
インターフェイスおよび CredentialInputUpdater
インターフェイスに移動されています。CredentialInputUpdater
インターフェイスを実装していない場合は、Red Hat build of Keycloak ストレージでプロバイダーが提供する認証情報をローカルで上書きできます。そのため、認証情報を読み取り専用にするには、CredentialInputUpdater.updateCredential()
メソッドを実装し、ReadOnlyException
を返します。
searchByAttributes()
、getGroupMembers()
などの UserFederationProvider
クエリーメソッドは、任意のインターフェイス UserQueryProvider
でカプセル化されるようになりました。このインターフェイスを実装しないと、ユーザーは管理コンソールでは表示されません。ただし、引き続きログインはできます。
6.13.3. UserFederationProviderFactory と UserStorageProviderFactory
以前の SPI の同期メソッドは、任意の ImportSynchronization
インターフェイス内でカプセル化されるようになりました。同期ロジックを実装している場合、新しい UserStorageProviderFactory
が ImportSynchronization
インターフェイスを実装します。
6.13.4. 新規モデルへのアップグレード
User Storage SPI インスタンスは異なるリレーショナルテーブルのセットに保存されます。Red Hat build of Keycloak は、移行スクリプトを自動的に実行します。以前のユーザーフェデレーションプロバイダーがレルムにデプロイされると、データの id
を含む、後のストレージモデルにそのまま変換されます。この移行は、以前のユーザーフェデレーションプロバイダーのプロバイダー ID ("ldap", "kerberos") と同じユーザーストレージプロバイダーが存在する場合のみ行われます。
そのため、この知識をもとに、さまざまなアプローチを取ることができます。
- 以前の Red Hat build of Keycloak デプロイメントでは、以前のプロバイダーを削除できます。これにより、インポートした全ユーザーのローカルリンクコピーが削除されます。その後、Red Hat build of Keycloak をアップグレードする際に、新しいプロバイダーをレルムにデプロイして設定します。
-
2 つ目のオプションは、
UserStorageProviderFactory.getId()
という同じプロバイダー ID を持つように新規プロバイダーを作成します。このプロバイダーがサーバーにデプロイされていることを確認します。サーバーを起動し、組み込み移行スクリプトが以前のデータモデルから後のデータモデルに変換されるようにします。この場合、以前にリンクしたインポート済みのユーザーはすべて機能し、同じ状態になります。
インポートストラテジーを廃止して、ユーザーストレージプロバイダーを書き換えた場合は、Red Hat build of Keycloak をアップグレードする前に以前のプロバイダーを削除することを推奨します。これにより、インポートしたユーザーにリンクされたローカルのインポートコピーが削除されます。