6.4. データプロバイダーおよびモデルの非推奨メソッド
以前に非推奨となったいくつかのメソッドが、Red Hat build of Keycloak で削除されました。
-
RealmModel#searchForGroupByNameStream(String, Integer, Integer)
-
UserProvider#getUsersStream(RealmModel, boolean)
-
UserSessionPersisterProvider#loadUserSessions(int, int, boolean, int, String)
-
Streamification 処理用に追加されたインターフェイス (
RoleMapperModel.Streams
など) -
KeycloakModelUtils#getClientScopeMappings
-
KeycloakSession
の非推奨メソッド -
UserQueryProvider#getUsersStream
メソッド
また、次のような他の変更も加えられました。
-
UserSessionProvider
の一部のメソッドがUserLoginFailureProvider
に移動しました。 -
フェデレーションストレージプロバイダークラスの
Streams
インターフェイスが非推奨になりました。 Streamification - インターフェイスにストリームベースのメソッドのみが含まれるようになりました。
たとえば、
GroupProvider
インターフェイスの場合:@Deprecated List<GroupModel> getGroups(RealmModel realm);
これは以下に置き換えられました。
Stream<GroupModel> getGroupsStream(RealmModel realm);
一貫したパラメーター順序付け -
RealmModel
が常に最初のパラメーターとなるように、メソッドに対して厳密なパラメーター順序付けが行われるようになりました。たとえば、
UserLookupProvider
インターフェイスの場合:@Deprecated UserModel getUserById(String id, RealmModel realm);
これは以下に置き換えられました。
UserModel getUserById(RealmModel realm, String id)
6.4.1. 変更されたインターフェイスのリスト
(o.k.
は org.keycloak.
パッケージを表します)
server-spi
モジュール-
o.k.credential.CredentialInputUpdater
-
o.k.credential.UserCredentialStore
-
o.k.models.ClientProvider
-
o.k.models.ClientSessionContext
-
o.k.models.GroupModel
-
o.k.models.GroupProvider
-
o.k.models.KeyManager
-
o.k.models.KeycloakSessionFactory
-
o.k.models.ProtocolMapperContainerModel
-
o.k.models.RealmModel
-
o.k.models.RealmProvider
-
o.k.models.RoleContainerModel
-
o.k.models.RoleMapperModel
-
o.k.models.RoleModel
-
o.k.models.RoleProvider
-
o.k.models.ScopeContainerModel
-
o.k.models.UserCredentialManager
-
o.k.models.UserModel
-
o.k.models.UserProvider
-
o.k.models.UserSessionProvider
-
o.k.models.utils.RoleUtils
-
o.k.sessions.AuthenticationSessionProvider
-
o.k.storage.client.ClientLookupProvider
-
o.k.storage.group.GroupLookupProvider
-
o.k.storage.user.UserLookupProvider
-
o.k.storage.user.UserQueryProvider
-
server-spi-private
モジュール-
o.k.events.EventQuery
-
o.k.events.admin.AdminEventQuery
-
o.k.keys.KeyProvider
-
6.4.2. ストレージ層でのリファクタリング
Red Hat build of Keycloak では、API の使用を簡素化するために大規模なリファクタリングが行われました。これは既存のコードに影響を与えます。以下の変更の中には、既存のコードの更新が必要なものもあります。以下のセクションでさらに詳しく説明します。
6.4.2.1. モジュール構造の変更
KeycloakSession
のストレージ機能に関するいくつかのパブリック API が統合されました。その一部は移動、非推奨化、または削除されました。3 つの新しいモジュールが導入され、server-spi
、server-spi-private
、および services
モジュールのデータ指向コードがそこに移動しました。
org.keycloak:keycloak-model-legacy
- User Storage API など、レガシーストアのパブリック API がすべて含まれます。
org.keycloak:keycloak-model-legacy-private
-
ストレージの
*Manager
クラスなど、ユーザーストレージ管理に関連するプライベート実装が含まれます。 org.keycloak:keycloak-model-legacy-services
- レガシーストアで直接動作するすべての REST エンドポイントが含まれます。
たとえば、新しいモジュールに移動したクラスをカスタムユーザーストレージプロバイダーの実装で使用している場合は、依存関係を更新して上記の新しいモジュールを含める必要があります。
6.4.2.2. KeycloakSession
の変更
KeycloakSession
が簡素化されました。KeycloakSession
のいくつかのメソッドが削除されました。
KeycloakSession
セッションには、特定のオブジェクトタイプのプロバイダーを取得するためのメソッドが含まれていました。たとえば、UserProvider
には、users()
、userLocalStorage()
、userCache()
、userStorageManager()
、および userFederatedStorage()
があります。このような状況は、各メソッドの正確な意味を理解する必要がある開発者にとってわかりにくい可能性があります。
これらの理由により、users()
メソッドのみが KeycloakSession
に保持されました。上記の他のすべての呼び出しは、このメソッドで置き換える必要があります。残りのメソッドは削除されました。同じ非推奨化のパターンが、client()
や groups()
などの他のオブジェクト領域のメソッドにも適用されます。末尾が *StorageManager()
および *LocalStorage()
のメソッドはすべて削除されました。次のセクションでは、これらの呼び出しを新しい API に移行する方法、またはレガシー API を使用する方法を説明します。
6.4.3. 既存のプロバイダーの移行
削除されたメソッドを呼び出さない場合、既存のプロバイダーを移行する必要はありません。これはほとんどのプロバイダーに当てはまります。
プロバイダーが削除されたメソッドを使用しているが、ローカルストレージと非ローカルストレージに依存していない場合は、削除された userLocalStorage()
から users()
メソッドに呼び出しを変更するのが最適です。ここでは、セマンティクスの変更に注意してください。ローカル設定でキャッシュが有効になっている場合、新しいメソッドにキャッシュが含まれるためです。
移行前: 削除された API へのアクセスがコンパイルされない
session.userLocalStorage();
移行後: 呼び出し元がレガシーストレージ API に依存していない場合、新しい API にアクセスする
session.users();
カスタムプロバイダーが特定のプロバイダーのモードを区別する必要がある稀なケースでは、非推奨オブジェクトへのアクセスを、LegacyStoreManagers
データストアプロバイダーを使用して提供します。これに該当するのは、プロバイダーがローカルストレージに直接アクセスする場合や、プロバイダーがキャッシュをスキップする場合などです。この方法は、レガシーモジュールがデプロイメントの一部である場合にのみ使用できます。
移行前: 削除された API にアクセスする
session.userLocalStorage();
移行後: LegacyStoreManagers API を介して新機能にアクセスする
((LegacyDatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();
一部のユーザーストレージ関連の API は、便宜上 org.keycloak.storage.UserStorageUtil
にラップされています。
6.4.4. RealmModel
への変更
メソッド getUserStorageProviders
、getUserStorageProvidersStream
、getClientStorageProviders
、getClientStorageProvidersStream
、getRoleStorageProviders
、および getRoleStorageProvidersStream
が削除されました。これらのメソッドに依存するコードは、次のようにインスタンスをキャストする必要があります。
移行前: API が変更されたため、コードがコンパイルされない
realm.getClientStorageProvidersStream()...;
移行後: インスタンスをレガシーインターフェイスにキャストする
((LegacyRealmModel) realm).getClientStorageProvidersStream()...;
同様に、以前 RealmModel
インターフェイスを実装していて、これらのメソッドを提供するコードは、新しいインターフェイス LegacyRealmModel
を実装する必要があります。このインターフェイスは RealmModel
のサブインターフェイスであり、古いメソッドを含んでいます。
移行前: 古いインターフェイスをコードが実装する
public class MyClass extends RealmModel {
/* might not compile due to @Override annotations for methods no longer present
in the interface RealmModel. / / ... */
}
移行後: 新しいインターフェイスをコードが実装する
public class MyClass extends LegacyRealmModel { /* ... */ }
6.4.5. UserCache
インターフェイスがレガシーモジュールに移動
オブジェクトのキャッシュステータスがサービスに対して透過的になるため、インターフェイス UserCache
がモジュール keycloak-model-legacy
に移動しました。
レガシー実装に依存するコードは、UserCache
に直接アクセスする必要があります。
移行前: コードがコンパイルされない [source,java,subs="+quotes"]
session**.userCache()**.evict(realm, user);
移行後: API を直接使用する
UserStorageUitl.userCache(session);
レルムの無効化をトリガーするには、UserCache
API を使用する代わりに、イベントをトリガーすることを検討してください。
移行前: コードがキャッシュ API を使用する [source,java,subs="+quotes"]
UserCache cache = session.getProvider(UserCache.class); if (cache != null) cache.evict(realm)();
移行後: 無効化 API を使用する
session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());
6.4.6. ユーザーの認証情報管理
ユーザーの認証情報は、以前は session.userCredentialManager().method(realm, user, ...)
を使用して管理されていました。新しい方法では、user.credentialManager().method(...)
を使用します。この形式は、認証情報の機能をユーザーの API に近づけるものであり、レルムとストレージに関するユーザー認証情報の場所の知識を前提としていません。
古い API は削除されました。
移行前: 削除された API にアクセスする
session.userCredentialManager().createCredential(realm, user, credentialModel)
移行後: 新しい API にアクセスする
user.credentialManager().createStoredCredential(credentialModel)
カスタムの UserStorageProvider
の場合、UserModel
を返すときに、新しいメソッド credentialManager()
を実装する必要があります。このメソッドは、LegacyUserCredentialManager
のインスタンスを返す必要があります。
移行前: UserModel
に新しいメソッド credentialManager()
が必要なため、コードがコンパイルされない
public class MyUserStorageProvider implements UserLookupProvider, ... { /* ... */ protected UserModel createAdapter(RealmModel realm, String username) { return new AbstractUserAdapter(session, realm, model) { @Override public String getUsername() { return username; } }; } }
移行後: レガシーストア用の API UserModel.credentialManager()
を実装する
public class MyUserStorageProvider implements UserLookupProvider, ... { /* ... */ protected UserModel createAdapter(RealmModel realm, String username) { return new AbstractUserAdapter(session, realm, model) { @Override public String getUsername() { return username; } @Override public SubjectCredentialManager credentialManager() { return new LegacyUserCredentialManager(session, realm, this); } }; } }