Chapter 6. Migrating custom providers

(o.k. stands for org.keycloak. package)

Red Hat build of Keycloak undergoes a large refactoring to simplify the API usage, which impacts existing code. Some of these changes require updates to existing code. The following sections provide more detail.

The existing providers need no migration if they do not call a removed method, which should be the case for most providers.

If the provider uses removed methods, but does not rely on local versus non-local storage, changing a call from the now removed userLocalStorage() to the method users() is the best option. Be aware that the semantics change here as the new method involves a cache if that has been enabled in the local setup.

This before migration example shows how accessing a removed API does not compile.

session.userLocalStorage();

session.userLocalStorage();

This post migration example shows accessing the new API when the caller does not depend on the storage API.

session.users();

session.users();

In the rare case when a custom provider needs to distinguish between the mode of a particular provider, access to the deprecated objects is provided by using the StoreManagers data store provider. This might be the case if the provider accesses the local storage directly or wants to skip the cache. This option will be available only if the storage modules are part of the deployment.

This before migration example shows accessing a removed API.

session.userLocalStorage();

session.userLocalStorage();

This post migration example shows accessing the new functionality by the StoreManagers API.

((DatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

((DatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

Some user storage related APIs have been wrapped in org.keycloak.storage.UserStorageUtil for convenience.

The methods getUserStorageProviders, getUserStorageProvidersStream, getClientStorageProviders, getClientStorageProvidersStream, getRoleStorageProviders and getRoleStorageProvidersStream have been removed. Code which depends on these methods should cast the instance as follows:

This before migration code example will not compile due to the changed API.

realm.getClientStorageProvidersStream()...;

realm.getClientStorageProvidersStream()...;

This post migration example casts the instance to the legacy interface.

((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

Similarly, code that used to implement the interface RealmModel and wants to provide these methods should implement the new interface LegacyRealmModel. This interface is a sub-interface of RealmModel and includes the old methods:

This before migration code example implements the old interface.

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 RealmModel {
    /* might not compile due to @Override annotations for methods no longer present
       in the interface RealmModel. / / ... */
}

This post migration code example implements the new interface.

public class MyClass extends LegacyRealmModel {
    /* ... */
}

public class MyClass extends LegacyRealmModel {
    /* ... */
}

As the caching status of objects will be transparent to services, the interface UserCache has been moved to the module keycloak-storage-legacy.

Code that depends on the legacy implementation should access the UserCache directly.

This before migration code example will not compile.

session.userCache().evict(realm, user);

session.userCache().evict(realm, user);

This post migration example shows using the API directly.

UserStorageUitl.userCache(session);

UserStorageUitl.userCache(session);

To trigger the invalidation of a realm, instead of using the UserCache API, consider triggering an event:

This before migration code example uses the cache API.

UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.evict(realm)();

UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.evict(realm)();

session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());

session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());

Credentials for users were previously managed using session.userCredentialManager().method(realm, user, ...). The new way is to leverage user.credentialManager().method(...). This form gets the credential functionality closer to the API of users, and does not rely on prior knowledge of the user credential’s location in regard to realm and storage.

The old APIs have been removed.

Before migration: accessing a removed API.

session.userCredentialManager().createCredential(realm, user, credentialModel)

session.userCredentialManager().createCredential(realm, user, credentialModel)

This post migration example shows accessing the new API.

user.credentialManager().createStoredCredential(credentialModel)

user.credentialManager().createStoredCredential(credentialModel)

For a custom UserStorageProvider, there is a new method credentialManager() that needs to be implemented when returning a UserModel. Those must return an instance of the UserCredentialManager:

This before migration code example will not compile due to the new method credentialManager() required by UserModel.

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}

This post migration example shows the implementation of the API UserModel.credentialManager() for the store.

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);
            }
        };
    }
}

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);
            }
        };
    }
}