Server Developer Guide

To authenticate against the Admin REST API using a client_id and a client_secret, perform this procedure.

Theme properties are set in the file <THEME TYPE>/theme.properties in the theme directory.

There are a list of properties that can be used to change the css class used for certain element types. For a list of these properties look at the theme.properties file in the corresponding type of the keycloak theme (themes/keycloak/<THEME TYPE>/theme.properties).

You can also add your own custom properties and use them from custom templates.

When doing so, you can substitute system properties or environment variables by using these formats:

A default value can also be provided in case the system property or the environment variable is not found with ${foo:defaultValue}.

Here’s an example of what is possible:

You can add one or more stylesheets to a theme.

You can add one or more scripts to a theme.

To make images available to the theme add them to the <THEME TYPE>/resources/img directory of your theme. These can be used from within stylesheets or directly in HTML templates.

For example to add an image to the mytheme copy an image to themes/mytheme/login/resources/img/image.jpg.

You can then use this image from within a custom stylesheet with:

Or to use directly in HTML templates add the following to a custom HTML template:

In order to use a custom footer, create a footer.ftl file in your custom login theme with the desired content.

An example for a custom footer.ftl may look like this:

To make images available to the theme add them to the <THEME TYPE>/email/resources/img directory of your theme. These can be used from within directly in HTML templates.

For example to add an image to the mytheme copy an image to themes/mytheme/email/resources/img/logo.jpg.

To use directly in HTML templates add the following to a custom HTML template:

Text in the templates is loaded from message bundles. A theme that extends another theme will inherit all messages from the parent’s message bundle and you can override individual messages by adding <THEME TYPE>/messages/messages_en.properties to your theme.

For example to replace Username on the login form with Your Username for the mytheme create the file themes/mytheme/login/messages/messages_en.properties with the following content:

Within a message values like {0} and {1} are replaced with arguments when the message is used. For example {0} in Log in to {0} is replaced with the name of the realm.

Texts of these message bundles can be overwritten by realm-specific values. The realm-specific values are manageable via UI and API.

By default, message properties files should be encoded using UTF-8. Keycloak falls back to ISO-8859-1 handling if it can’t read the contents as UTF-8. Unicode characters can be escaped as described in Java’s documentation for PropertyResourceBundle. Previous versions of Keycloak supported specifying the encoding in the first line with a comment like # encoding: UTF-8, which is no longer supported.

Keycloak supports adding icons for custom Identity providers, which are displayed on the login screen.

All icons are available on the official website of PatternFly4. Icons for social providers are already defined in base login theme properties (themes/keycloak/login/theme.properties), where you can inspire yourself.

Keycloak uses Apache Freemarker templates to generate HTML and render pages.

Although it is possible to create custom templates to change completely how pages are rendered, the recommendation is to leverage the built-in templates as much as possible. The reasons are:

In most cases, you won’t need to change templates to adapt Keycloak to your needs, but you can override individual templates in your own theme by creating <THEME TYPE>/<TEMPLATE>.ftl. Admin and account console use a single template index.ftl for rendering the application.

For a list of templates in other theme types look at the theme/base/<THEME_TYPE> directory in the JAR file at $KEYCLOAK_HOME/lib/lib/main/org.keycloak.keycloak-themes-<VERSION>.jar.

To edit the subject and contents for emails, for example password recovery email, add a message bundle to the email type of your theme. There are three messages for each email. One for the subject, one for the plain text body and one for the html body.

To see all emails available take a look at themes/base/email/messages/messages_en.properties.

For example to change the password recovery email for the mytheme theme create themes/mytheme/email/messages/messages_en.properties with the following content:

If you are using the external token generated by logging into the provider (i.e. a Facebook or GitHub token), you can refresh this token by re-initiating the account linking API.

As mentioned above, it is recommended that your ProviderFactory implementations use unique ID. However at the same time, it can be useful to override one of the Keycloak built-in providers. The recommended way for this is still ProviderFactory implementation with unique ID and then for instance set the default provider as specified in the Configuring Providers guide. On the other hand, this may not be always possible.

For instance when you need some customizations to default OpenID Connect protocol behaviour and you want to override default Keycloak implementation of OIDCLoginProtocolFactory you need to preserve same providerId. As for example admin console, OIDC protocol well-known endpoint and various other things rely on the ID of the protocol factory being openid-connect.

For this case, it is highly recommended to implement method order() of your custom implementation and make sure that it has higher order than the built-in implementation.

In case of multiple implementations with same provider ID, only the one with highest order will be used by Keycloak runtime.

Sometimes it is useful to show additional info about your Provider to a Keycloak administrator. You can show provider build time information (for example, version of custom provider currently installed), current configuration of the provider (e.g. url of remote system your provider talks to) or some operational info (average time of response from remote system your provider talks to). Keycloak Admin Console provides Server Info page to show this kind of information.

To show info from your provider it is enough to implement org.keycloak.provider.ServerInfoAwareProviderFactory interface in your ProviderFactory.

Example implementation for MyThemeSelectorProviderFactory from previous example:

You can disable a provider by setting the enabled attribute for the provider to false. For example to disable the Infinispan user cache provider use:

Authentication scripts must provide at least one of the following functions: authenticate(..), which is called from Authenticator#authenticate(AuthenticationFlowContext) action(..), which is called from Authenticator#action(AuthenticationFlowContext)

Custom Authenticator should at least provide the authenticate(..) function. You can use the javax.script.Bindings script within the code.

OpenID Connect Protocol Mapper scripts are javascript script that allow you to change the content of the ID Token and/or the Access Token.

You can use the javax.script.Bindings script within the code.

The exports of the script will be used as the value of the token claim.

The above script allows to retrieve a user_input from the authorization request. This will be available to map in the Token Claim Name configured in the mapper.

In order to make your scripts available to Keycloak you need to deploy them to the server. For that, you should create a JAR file with the following structure:

The META-INF/keycloak-scripts.json is a file descriptor that provides metadata information about the scripts you want to deploy. It is a JSON file with the following structure:

This file should reference the different types of script providers that you want to deploy:

For each script file in your JAR file, you need a corresponding entry in META-INF/keycloak-scripts.json that maps your scripts files to a specific provider type. For that you should provide the following properties for each entry:

Once you have a JAR file with a descriptor and the scripts you want to deploy, you just need to copy the JAR to the Keycloak providers/ directory, then run bin/kc.[sh|bat] build.

You will package your classes within a single jar. This jar must contain a file named org.keycloak.authentication.AuthenticatorFactory and must be contained in the META-INF/services/ directory of your jar. This file must list the fully qualified class name of each AuthenticatorFactory implementation you have in the jar. For example:

This services/ file is used by Keycloak to scan the providers it has to load into the system.

To deploy this jar, just copy it to the providers directory.

In Keycloak, credentials are stored in the database in the Credentials table. It has the following structure:

Where:

As the secret_data and credential_data fields are designed to contain json, it is up to you to determine how to structure, read and write into these fields, allowing you a lot of flexibility.

For this example, we are going to use a very simple credential data, containing only the question asked to the user:

with an equally simple secret data, containing only the secret answer:

Here the answer will be kept in plain text in the database for the sake of simplicity, but it would also be possible to have a salted hash for the answer, as is the case for passwords in Keycloak. In this case, the secret data would also have to contain a field for the salt, and the credential data information about the algorithm such as the type of algorithm used and the number of iterations used. For more details you can consult the implementation of the org.keycloak.models.credential.PasswordCredentialModel class.

In our case we create the class SecretQuestionCredentialModel:

Where TYPE is the credential_type we write in the database. For consistency, we make sure that this String is always the one referenced when getting the type for this credential. The classes SecretQuestionCredentialData and SecretQuestionSecretData are used to marshal and unmarshal the json:

To be fully usable, the SecretQuestionCredentialModel objects must both contain the raw json data from its parent class, and the unmarshalled objects in its own attributes. This leads us to create a method which reads from a simple CredentialModel, such as is created when reading from the database, to make a SecretQuestionCredentialModel:

And a method to create a SecretQuestionCredentialModel from the question and answer:

As with all Providers, to allow Keycloak to generate the CredentialProvider, we require a CredentialProviderFactory. For this requirement we create the SecretQuestionCredentialProviderFactory, whose create method will be called when a SecretQuestionCredentialProvider is asked for:

The CredentialProvider interface takes a generic parameter that extends a CredentialModel. In our case we to use the SecretQuestionCredentialModel we created:

We also want to implement the CredentialInputValidator interface, as this allows Keycloak to know that this provider can also be used to validate a credential for an Authenticator. For the CredentialProvider interface, the first method that needs to be implemented is the getType() method. This will simply return the `SecretQuestionCredentialModel’s TYPE String:

The second method is to create a SecretQuestionCredentialModel from a CredentialModel. For this method we simply call the existing static method from SecretQuestionCredentialModel:

Finally, we have the methods to create a credential and delete a credential. These methods call the UserModel’s credential manager, which is responsible for knowing where to read or write the credential, for example local storage or federated storage.

For the CredentialInputValidator, the main method to implement is the isValid, which tests whether a credential is valid for a given user in a given realm. This is the method that is called by the Authenticator when it seeks to validate the user’s input. Here we simply need to check that the input String is the one recorded in the Credential:

The other two methods to implement are a test if the CredentialProvider supports the given credential type and a test to check if the credential type is configured for a given user. For our case, the latter test simply means checking if the user has a credential of the SECRET_QUESTION type:

When implementing an authenticator that uses Credentials to authenticate a user, you should have the authenticator implement the CredentialValidator interface. This interfaces takes a class extending a CredentialProvider as a parameter, and will allow Keycloak to directly call the methods from the CredentialProvider. The only method that needs to be implemented is getCredentialProvider method, which in our example allows the SecretQuestionAuthenticator to retrieve the SecretQuestionCredentialProvider:

When implementing the Authenticator interface, the first method that needs to be implemented is the requiresUser() method. For our example, this method must return true as we need to validate the secret question associated with the user. A provider like kerberos would return false from this method as it can resolve a user from the negotiate header. This example, however, is validating a specific credential of a specific user.

The next method to implement is the configuredFor() method. This method is responsible for determining if the user is configured for this particular authenticator. In our case, we can just call the method implemented in the SecretQuestionCredentialProvider

The next method to implement on the Authenticator is setRequiredActions(). If configuredFor() returns false and our example authenticator is required within the flow, this method will be called, but only if the associated AuthenticatorFactory’s isUserSetupAllowed method returns true. The setRequiredActions() method is responsible for registering any required actions that must be performed by the user. In our example, we need to register a required action that will force the user to set up the answer to the secret question. We will implement this required action provider later in this chapter. Here is the implementation of the setRequiredActions() method.

Now we are getting into the meat of the Authenticator implementation. The next method to implement is authenticate(). This is the initial method the flow invokes when the execution is first visited. What we want is that if a user has answered the secret question already on their browser’s machine, then the user doesn’t have to answer the question again, making that machine "trusted". The authenticate() method isn’t responsible for processing the secret question form. Its sole purpose is to render the page or to continue the flow.

The hasCookie() method checks to see if there is already a cookie set on the browser which indicates that the secret question has already been answered. If that returns true, we just mark this execution’s status as SUCCESS using the AuthenticationFlowContext.success() method and returning from the authentication() method.

If the hasCookie() method returns false, we must return a response that renders the secret question HTML form. AuthenticationFlowContext has a form() method that initializes a Freemarker page builder with appropriate base information needed to build the form. This page builder is called org.keycloak.login.LoginFormsProvider. The LoginFormsProvider.createForm() method loads a Freemarker template file from your login theme. Additionally you can call the LoginFormsProvider.setAttribute() method if you want to pass additional information to the Freemarker template. We’ll go over this later.

Calling LoginFormsProvider.createForm() returns a JAX-RS Response object. We then call AuthenticationFlowContext.challenge() passing in this response. This sets the status of the execution as CHALLENGE and if the execution is Required, this JAX-RS Response object will be sent to the browser.

So, the HTML page asking for the answer to a secret question is displayed to the user and the user enters in the answer and clicks submit. The action URL of the HTML form will send an HTTP request to the flow. The flow will end up invoking the action() method of our Authenticator implementation.

If the answer is not valid, we rebuild the HTML Form with an additional error message. We then call AuthenticationFlowContext.failureChallenge() passing in the reason for the value and the JAX-RS response. failureChallenge() works the same as challenge(), but it also records the failure so it can be analyzed by any attack detection service.

If validation is successful, then we set a cookie to remember that the secret question has been answered and we call AuthenticationFlowContext.success().

The validation itself gets the data that was received from the form, and calls the isValid method from the SecretQuestionCredentialProvider. You’ll notice that there’s a section of the code concerning getting the credential Id. This is because if Keycloak is configured to allow multiple types of alternative authenticators, or if the user could record multiple credentials of the SECRET_QUESTION type (for example if we allowed to choose from several questions, and we allowed the user to have answers for more than one of those questions), then Keycloak needs to know which credential is being used to log the user. In case there is more than one credential, Keycloak allows the user to choose during the login which credential is being used, and the information is transmitted by the form to the Authenticator. In case the form doesn’t present this information, credential id used is given by the CredentialProvider’s default getDefaultCredential method, which will return the "most preferred" credential of the correct type of the user,

Next method is the setCookie(). This is an example of providing configuration for the Authenticator. In this case we want the max age of the cookie to be configurable.

We obtain an AuthenticatorConfigModel from the AuthenticationFlowContext.getAuthenticatorConfig() method. If configuration exists we pull the max age config out of it. We will see how we can define what should be configured when we talk about the AuthenticatorFactory implementation. The config values can be defined within the Admin Console if you set up config definitions in your AuthenticatorFactory implementation.

The last method to implement in the SecretQuestionCredentialProvider class is getCredentialTypeMetadata(CredentialTypeMetadataContext metadataContext), which is an abstract method of the CredentialProvider interface. Each Credential provider has to provide and implement this method. The method returns an instance of CredentialTypeMetadata, which should at least include type and category of authenticator, displayName and removable item. In this example, the builder takes type of authenticator from method getType(), category is Two Factor (the authenticator can be used as second factor of authentication) and removable, which is set up to false (user can’t remove some previously registered credentials).

Other items of builder are helpText (will be shown to the user on various screens), createAction (the providerID of the required action, which can be used by the user to create new credential) or updateAction (same as createAction, but instead of creating the new credential, it will update the credential).

The next step in this process is to implement an AuthenticatorFactory. This factory is responsible for instantiating an Authenticator. It also provides deployment and configuration metadata about the Authenticator.

The getId() method is just the unique name of the component. The create() method is called by the runtime to allocate and process the Authenticator.

The next thing the factory is responsible for is to specify the allowed requirement switches. While there are four different requirement types: ALTERNATIVE, REQUIRED, CONDITIONAL, DISABLED, AuthenticatorFactory implementations can limit which requirement options are shown in the Admin Console when defining a flow. CONDITIONAL should only always be used for subflows, and unless there’s a good reason for doing otherwise, the requirement on an authenticator should be REQUIRED, ALTERNATIVE and DISABLED:

The AuthenticatorFactory.isUserSetupAllowed() is a flag that tells the flow manager whether or not Authenticator.setRequiredActions() method will be called. If an Authenticator is not configured for a user, the flow manager checks isUserSetupAllowed(). If it is false, then the flow aborts with an error. If it returns true, then the flow manager will invoke Authenticator.setRequiredActions().

The next few methods define how the Authenticator can be configured. The isConfigurable() method is a flag which specifies to the Admin Console on whether the Authenticator can be configured within a flow. The getConfigProperties() method returns a list of ProviderConfigProperty objects. These objects define a specific configuration attribute.

Each ProviderConfigProperty defines the name of the config property. This is the key used in the config map stored in AuthenticatorConfigModel. The label defines how the config option will be displayed in the Admin Console. The type defines if it is a String, Boolean, or other type. The Admin Console will display different UI inputs depending on the type. The help text is what will be shown in the tooltip for the config attribute in the Admin Console. Read the javadoc of ProviderConfigProperty for more detail.

The rest of the methods are for the Admin Console. getHelpText() is the tooltip text that will be shown when you are picking the Authenticator you want to bind to an execution. getDisplayType() is the text that will be shown in the Admin Console when listing the Authenticator. getReferenceCategory() is just a category the Authenticator belongs to.

Keycloak comes with a Freemarker theme and template engine. The createForm() method you called within authenticate() of your Authenticator class, builds an HTML page from a file within your login theme: secret-question.ftl. This file should be added to the theme-resources/templates in your JAR, see Theme Resource Provider for more details.

Let’s take a bigger look at secret-question.ftl Here’s a small code snippet:

Any piece of text enclosed in ${} corresponds to an attribute or template function. If you see the form’s action, you see it points to ${url.loginAction}. This value is automatically generated when you invoke the AuthenticationFlowContext.form() method. You can also obtain this value by calling the AuthenticationFlowContext.getActionURL() method in Java code.

You’ll also see ${properties.someValue}. These correspond to properties defined in your theme.properties file of our theme. ${msg("someValue")} corresponds to the internationalized message bundles (.properties files) included with the login theme messages/ directory. If you’re just using english, you can just add the value of the loginSecretQuestion. This should be the question you want to ask the user.

When you call AuthenticationFlowContext.form() this gives you a LoginFormsProvider instance. If you called, LoginFormsProvider.setAttribute("foo", "bar"), the value of "foo" would be available for reference in your form as ${foo}. The value of an attribute can be any Java bean as well.

If you look at the top of the file, you’ll see that we are importing a template:

Importing this template, instead of the standard template.ftl allows Keycloak to display a dropdown box that allows the user to select a different credential or execution.

Adding an Authenticator to a flow must be done in the Admin Console. If you go to the Authentication menu item and go to the Flow tab, you will be able to view the currently defined flows. You cannot modify built in flows, so, to add the Authenticator we’ve created you have to copy an existing flow or create your own. Our hope is that the user interface is sufficiently clear so that you can determine how to create a flow and add the Authenticator. For more details, see the Authentication Flows chapter in Server Administration Guide .

After you’ve created your flow, you have to bind it to the login action you want to bind it to. If you go to the Authentication menu and go to the Bindings tab you will see options to bind a flow to the browser, registration, or direct grant flow.

You will package your classes within a single jar. This jar does not have to be separate from other provider classes but it must contain a file named org.keycloak.authentication.RequiredActionFactory and must be contained in the META-INF/services/ directory of your jar. This file must list the fully qualified classname of each RequiredActionFactory implementation you have in the jar. For example:

This services/ file is used by Keycloak to scan the providers it has to load into the system.

To deploy this jar, copy it to the providers/ directory, then run bin/kc.[sh|bat] build.

Required actions must first implement the RequiredActionProvider interface. The RequiredActionProvider.requiredActionChallenge() is the initial call by the flow manager into the required action. This method is responsible for rendering the HTML form that will drive the required action.

You see that RequiredActionContext has similar methods to AuthenticationFlowContext. The form() method allows you to render the page from a Freemarker template. The action URL is preset by the call to this form() method. You just need to reference it within your HTML form. I’ll show you this later.

The challenge() method notifies the flow manager that a required action must be executed.

The next method is responsible for processing input from the HTML form of the required action. The action URL of the form will be routed to the RequiredActionProvider.processAction() method

The answer is pulled out of the form post. A UserCredentialValueModel is created and the type and value of the credential are set. Then UserModel.updateCredentialDirectly() is invoked. Finally, RequiredActionContext.success() notifies the container that the required action was successful.

This class is really simple. It is just responsible for creating the required action provider instance.

The getDisplayText() method is just for the Admin Console when it wants to display a friendly name for the required action.

The final thing you have to do is go into the Admin Console. Click on the Authentication left menu. Click on the Required Actions tab. Click on the Register button and choose your new Required Action. Your new required action should now be displayed and enabled in the required actions list.

The core interface you have to implement is the FormAction interface. A FormAction is responsible for rendering and processing a portion of the page. Rendering is done in the buildPage() method, validation is done in the validate() method, post validation operations are done in success(). Let’s first take a look at buildPage() method of the Recaptcha plugin.

The Recaptcha buildPage() method is a callback by the form flow to help render the page. It receives a form parameter which is a LoginFormsProvider. You can add additional attributes to the form provider so that they can be displayed in the HTML page generated by the registration Freemarker template.

The code above is from the registration recaptcha plugin. Recaptcha requires some specific settings that must be obtained from configuration. FormActions are configured in the exact same as Authenticators are. In this example, we pull the Google Recaptcha site key and other options from Recaptcha configuration and add them as attributes to the form provider. Our registration template file, register.ftl, can now have access to those attributes.

Recaptcha also has the requirement of loading a JavaScript script. You can do this by calling LoginFormsProvider.addScript(), passing in the URL.

For user profile processing, there is no additional information that it needs to add to the form, so its buildPage() method is empty.

The next meaty part of this interface is the validate() method. This is called immediately upon receiving a form post. Let’s look at the Recaptcha’s plugin first.

Here we obtain the form data that the Recaptcha widget adds to the form. We obtain the Recaptcha secret key from configuration. We then validate the recaptcha. If successful, ValidationContext.success() is called. We clear the captcha token from the form using formData.remove, but keep other form data untouched. If not, we invoke ValidationContext.validationError() passing in the formData (so the user doesn’t have to re-enter data), we also specify an error message we want displayed. The error message must point to a message bundle property in the internationalized message bundles. For other registration extensions validate() might be validating the format of a form element, for example an alternative email attribute.

Let’s also look at the user profile plugin that is used to validate email address and other user information when registering.

As you can see, this validate() method of user profile processing makes sure that the email and all other attributes are filled in the form. It delegates to User Profile SPI, which makes sure that email is in the right format and does all other validations. If any of these validations fail, an error message is queued up for rendering. It would contain the message for every field where the validation failed.

After all validations have been processed then, the form flow then invokes the FormAction.success() method. For recaptcha this is a no-op, so we won’t go over it. For user profile processing, this method fills in values in the registered user.

The new user is created and the UserModel of the newly registered user is added to the FormContext. The appropriate methods are called to initialize UserModel data. In your own FormAction, you can possibly obtain user by using something like:

Finally, you are also required to define a FormActionFactory class. This class is implemented similarly to AuthenticatorFactory, so we won’t go over it.

You will package your classes within a single jar. This jar must contain a file named org.keycloak.authentication.FormActionFactory and must be contained in the META-INF/services/ directory of your jar. This file must list the fully qualified class name of each FormActionFactory implementation you have in the jar. For example:

This services/ file is used by Keycloak to scan the providers it has to load into the system.

To deploy this jar, copy it to the providers/ directory, then run bin/kc.[sh|bat] build.

Adding a FormAction to a registration page flow must be done in the Admin Console. If you go to the Authentication menu item and go to the Flow tab, you will be able to view the currently defined flows. You cannot modify built in flows, so, to add the Authenticator we’ve created you have to copy an existing flow or create your own. I’m hoping the UI is intuitive enough so that you can figure out for yourself how to create a flow and add the FormAction.

Basically you’ll have to copy the registration flow. Then click Actions menu to the right of the Registration Form, and pick "Add execution" to add a new execution. You’ll pick the FormAction from the selection list. Make sure your FormAction comes after "Registration User Creation" by using the down buttons to move it if your FormAction isn’t already listed after "Registration User Creation". You want your FormAction to come after user creation because the success() method of Registration User Creation is responsible for creating the new UserModel.

After you’ve created your flow, you have to bind it to registration. If you go to the Authentication menu and go to the Bindings tab you will see options to bind a flow to the browser, registration, or direct grant flow.

Actually Keycloak has 2 default implementations of client authentication:

See the demo example and especially the examples/preconfigured-demo/product-app for the example application showing the application using client authentication with signed JWT.

For plug your own client authenticator, you need to implement few interfaces on both client (adapter) and server side.

As action token is just a signed JWT with few mandatory fields (see Anatomy of action token above), it can be serialized and signed as such using Keycloak’s JWSBuilder class. This way has been already implemented in serialize(session, realm, uriInfo) method of org.keycloak.authentication.actiontoken.DefaultActionToken and can be leveraged by implementers by using that class for tokens instead of plain JsonWebToken.

The following example shows the implementation of a simple action token. Note that the class must have a private constructor without any arguments. This is necessary to deserialize the token class from JWT.

If the action token you are implementing contains any custom fields that should be serializabled to JSON fields, you should consider implementing a descendant of org.keycloak.representations.JsonWebToken class that would implement org.keycloak.models.ActionTokenKeyModel interface. In that case, you can take advantage of the existing org.keycloak.authentication.actiontoken.DefaultActionToken class as it already satisfies both these conditions, and either use it directly or implement its child, the fields of which can be annotated with appropriate Jackson annotations, e.g. com.fasterxml.jackson.annotation.JsonProperty to serialize them to JSON.

The following example extends the DemoActionToken from the previous example with the field demo-id:

To plug your own action token and its handler, you need to implement few interfaces on server side:

One important method of UserModel is the getId() method. When implementing UserModel developers must be aware of the user id format. The format must be:

The Keycloak runtime often has to look up users by their user id. The user id contains enough information so that the runtime does not have to query every single UserStorageProvider in the system to find the user.

The component id is the id returned from ComponentModel.getId(). The ComponentModel is passed in as a parameter when creating the provider class so you can get it from there. The external id is information your provider class needs to find the user in the external store. This is often a username or a uid. For example, it might look something like this:

When the runtime does a lookup by id, the id is parsed to obtain the component id. The component id is used to locate the UserStorageProvider that was originally used to load the user. That provider is then passed the id. The provider again parses the id to obtain the external id and it will use to locate the user in external user storage.

This format has the drawback that it can generate long IDs for the external storage users. This is specially important when combined with the WebAuthn authentication, which limits the user handle ID to 64 bytes. For that reason, if the storage users are going to use WebAuthn authentication, it is important to limit the full storage ID to 64 characters. The method validateConfiguration can be used to assign a short ID for the provider component on creation, giving some space to the user IDs within the 64 byte limitation.

The first thing we will walk through is the UserStorageProvider class.

Our provider class, PropertyFileUserStorageProvider, implements many interfaces. It implements the UserStorageProvider as that is a base requirement of the SPI. It implements the UserLookupProvider interface because we want to be able to log in with users stored by this provider. It implements the CredentialInputValidator interface because we want to be able to validate passwords entered in using the login screen. Our property file is read-only. We implement the CredentialInputUpdater because we want to post an error condition when the user attempts to update his password.

The constructor for this provider class is going to store the reference to the KeycloakSession, ComponentModel, and property file. We’ll use all of these later. Also notice that there is a map of loaded users. Whenever we find a user we will store it in this map so that we avoid re-creating it again within the same transaction. This is a good practice to follow as many providers will need to do this (that is, any provider that integrates with JPA). Remember also that provider class instances are created once per transaction and are closed after the transaction completes.

Now that the provider class is complete, we now turn our attention to the provider factory class.

First thing to notice is that when implementing the UserStorageProviderFactory class, you must pass in the concrete provider class implementation as a template parameter. Here we specify the provider class we defined before: PropertyFileUserStorageProvider.

The getId() method identifies the factory in the runtime and will also be the string shown in the admin console when you want to enable a user storage provider for the realm.

The class files for our provider implementation should be placed in a jar. You also have to declare the provider factory class within the META-INF/services/org.keycloak.storage.UserStorageProviderFactory file.

To deploy this jar, copy it to the providers/ directory, then run bin/kc.[sh|bat] build.

You enable user storage providers per realm within the User Federation page in the Admin Console.

You will now be able to log in with a user declared in the users.properties file. This user will only be able to view the account page after logging in.

Let’s expand our PropertyFileUserStorageProviderFactory example to allow you to point a provider instance to a specific file on disk.

The ProviderConfigurationBuilder class is a great helper class to create a list of configuration properties. Here we specify a variable named path that is a String type. On the Admin Console configuration page for this provider, this configuration variable is labeled as Path and has a default value of ${jboss.server.config.dir}/example-users.properties. When you hover over the tooltip of this configuration option, it displays the help text, File path to properties file.

The next thing we want to do is to verify that this file exists on disk. We do not want to enable an instance of this provider in the realm unless it points to a valid user property file. To do this, we implement the validateConfiguration() method.

The validateConfiguration() method provides the configuration variable from the ComponentModel to verify if that file exists on disk. Notice that the use of the org.keycloak.common.util.EnvUtil.replace() method. With this method any string that includes ${} will replace that value with a system property value. The ${jboss.server.config.dir} string corresponds to the conf/ directory of our server and is really useful for this example.

Next thing we have to do is remove the old init() method. We do this because user property files are going to be unique per provider instance. We move this logic to the create() method.

This logic is, of course, inefficient as every transaction reads the entire user property file from disk, but hopefully this illustrates, in a simple way, how to hook in configuration variables.

Now that the configuration is enabled, you can set the path variable when you configure the provider in the Admin Console.

Use this procedure to implement adding and removing users from the particular store, we first have to be able to save our properties file to disk.

Then, the implementation of the addUser() and removeUser() methods becomes simple.

Notice that when adding a user we set the password value of the property map to be UNSET_PASSWORD. We do this as we can’t have null values for a property in the property value. We also have to modify the CredentialInputValidator methods to reflect this.

The addUser() method will be called if the provider implements the UserRegistrationProvider interface. If your provider has a configuration switch to turn off adding a user, returning null from this method will skip the provider and call the next one.

Since we can now save our property file, it also makes sense to allow password updates.

We can now also implement disabling a password.

With these methods implemented, you’ll now be able to change and disable the password for the user in the Admin Console.

UserQueryProvider is combination of UserQueryMethodsProvider and UserCountMethodsProvider. Without implementing UserQueryMethodsProvider the Admin Console would not be able to view and manage users that were loaded by our example provider. Let’s look at implementing this interface.

The first declaration of searchForUserStream() takes a String parameter. In this example, the parameter represents a username that you want to search by. This string can be a substring, which explains the choice of the String.contains() method when doing the search. Notice the use of * to indicate to request a list of all users. The method iterates over the key set of the property file, delegating to getUserByUsername() to load a user. Notice that we are indexing this call based on the firstResult and maxResults parameter. If your external store does not support pagination, you will have to do similar logic.

The searchForUserStream() method that takes a Map parameter can search for a user based on first, last name, username, and email. Only usernames are stored, so the search is based only on usernames except when the Map parameter does not contain the username attribute. In this case, all users are returned. In that situation, the searchForUserStream(realm, search, firstResult, maxResults) is used.

Groups or attributes are not stored, so the other methods return an empty stream.

In our PropertyFileUserStorageProvider example, we just need a simple change to our provider to use the AbstractUserAdapterFederatedStorage.

We instead define an anonymous class implementation of AbstractUserAdapterFederatedStorage. The setUsername() method makes changes to the properties file and saves it.

If you remember earlier in this chapter, we discussed how querying for a user worked. Local storage is queried first, if the user is found there, then the query ends. This is a problem for our above implementation as we want to proxy the local UserModel so that we can keep usernames in sync. The User Storage SPI has a callback for whenever a linked local user is loaded from the local database.

Whenever a linked local user is loaded, if the user storage provider class implements this interface, then the validate() method is called. Here you can proxy the local user passed in as a parameter and return it. That new UserModel will be used. You can also optionally do a check to see if the user still exists in the external store. If validate() returns null, then the local user will be removed from the database.

With the import strategy you can see that it is possible for the local user copy to get out of sync with external storage. For example, maybe a user has been removed from the external store. The User Storage SPI has an additional interface you can implement to deal with this, org.keycloak.storage.user.ImportSynchronization:

This interface is implemented by the provider factory. Once this interface is implemented by the provider factory, the administration console management page for the provider shows additional options. You can manually force a synchronization by clicking a button. This invokes the ImportSynchronization.sync() method. Also, additional configuration options are displayed that allow you to automatically schedule a synchronization. Automatic synchronizations invoke the syncSince() method.

You can access the user cache by calling KeycloakSession.getProvider(UserCache.class).

There are methods for evicting specific users, users contained in a specific realm, or the entire cache.

You might want to cache additional information that is specific to your provider implementation. The User Storage SPI has a callback whenever a user is cached: org.keycloak.models.cache.OnUserCache.

Your provider class should implement this interface if it wants this callback. The UserModel delegate parameter is the UserModel instance returned by your provider. The CachedUserModel is an expanded UserModel interface. This is the instance that is cached locally in local storage.

This CachedUserModel interface allows you to evict the user from the cache and get the provider UserModel instance. The getCachedWith() method returns a map that allows you to cache additional information pertaining to the user. For example, credentials are not part of the UserModel interface. If you wanted to cache credentials in memory, you would implement OnUserCache and cache your user’s credentials using the getCachedWith() method.

On the administration console management page for your user storage provider, you can specify a unique cache policy.

The earlier User Federation SPI required you to create a local copy of a user in the Keycloak’s database and import information from your external store to the local copy. However, this is no longer a requirement. You can still port your earlier provider as-is, but you should consider whether a non-import strategy might be a better approach.

Advantages of the import strategy:

There are some obvious disadvantages though to using an import strategy:

The first thing to notice is that UserFederationProvider was a complete interface. You implemented every method in this interface. However, UserStorageProvider has instead broken up this interface into multiple capability interfaces that you implement as needed.

UserFederationProvider.getUserByUsername() and getUserByEmail() have exact equivalents in the new SPI. The difference between the two is how you import. If you are going to continue with an import strategy, you no longer call KeycloakSession.userStorage().addUser() to create the user locally. Instead you call KeycloakSession.userLocalStorage().addUser(). The userStorage() method no longer exists.

The UserFederationProvider.validateAndProxy() method has been moved to an optional capability interface, ImportedUserValidation. You want to implement this interface if you are porting your earlier provider as-is. Also note that in the earlier SPI, this method was called every time the user was accessed, even if the local user is in the cache. In the later SPI, this method is only called when the local user is loaded from local storage. If the local user is cached, then the ImportedUserValidation.validate() method is not called at all.

The UserFederationProvider.isValid() method no longer exists in the later SPI.

The UserFederationProvider methods synchronizeRegistrations(), registerUser(), and removeUser() have been moved to the UserRegistrationProvider capability interface. This new interface is optional to implement so if your provider does not support creating and removing users, you don’t have to implement it. If your earlier provider had switch to toggle support for registering new users, this is supported in the new SPI, returning null from UserRegistrationProvider.addUser() if the provider doesn’t support adding users.

The earlier UserFederationProvider methods centered around credentials are now encapsulated in the CredentialInputValidator and CredentialInputUpdater interfaces, which are also optional to implement depending on if you support validating or updating credentials. Credential management used to exist in UserModel methods. These also have been moved to the CredentialInputValidator and CredentialInputUpdater interfaces. One thing to note that if you do not implement the CredentialInputUpdater interface, then any credentials provided by your provider can be overridden locally in Keycloak storage. So if you want your credentials to be read-only, implement the CredentialInputUpdater.updateCredential() method and return a ReadOnlyException.

The UserFederationProvider query methods such as searchByAttributes() and getGroupMembers() are now encapsulated in an optional interface UserQueryProvider. If you do not implement this interface, then users will not be viewable in the admin console. You’ll still be able to log in though.

The synchronization methods in the earlier SPI are now encapsulated within an optional ImportSynchronization interface. If you have implemented synchronization logic, then have your new UserStorageProviderFactory implement the ImportSynchronization interface.

The User Storage SPI instances are stored in a different set of relational tables. Keycloak automatically runs a migration script. If any earlier User Federation providers are deployed for a realm, they are converted to the later storage model as is, including the id of the data. This migration will only happen if a User Storage provider exists with the same provider ID (i.e., "ldap", "kerberos") as the earlier User Federation provider.

So, knowing this there are different approaches you can take.

If you have decided to get rid of the import strategy and rewrite your User Storage provider, we suggest that you remove the earlier provider before upgrading Keycloak. This will remove linked local imported copies of any user you imported.