Server Administration Guide

A locale selector provider suggests the best locale on the information available. However, it is often unknown who the user is. For this reason, the previously authenticated user’s locale is remembered in a persisted cookie.

The logic for selecting the locale uses the first of the following that is available:

When a user is authenticated an action is triggered to update the locale in the persisted cookie mentioned earlier. If the user has actively switched the locale through the locale selector on the login pages the users locale is also updated at this point.

If you want to change the logic for selecting the locale, you have an option to create custom LocaleSelectorProvider. For details, please refer to the Server Developer Guide.

If you enable Forgot password, users can reset their login credentials if they forget their passwords or lose their OTP generator.

The text sent in the email is configurable. See Server Developer Guide for more information.

When users click the email link, Red Hat build of Keycloak asks them to update their password, and if they have set up an OTP generator, Red Hat build of Keycloak asks them to reconfigure the OTP generator. Depending on security requirements of your organization, you may not want users to reset their OTP generator through email.

To change this behavior, perform these steps:

A logged-in user closing their browser destroys their session, and that user must log in again. You can set Red Hat build of Keycloak to keep the user’s login session open if that user clicks the Remember Me checkbox upon login. This action turns the login cookie from a session-only cookie to a persistence cookie.

In the general settings of a realm, you can define which Authentication Context Class Reference (ACR) value is mapped to which Level of Authentication (LoA). The ACR can be any value, whereas the LoA must be numeric. The acr claim can be requested in the claims or acr_values parameter sent in the OIDC request and it is also included in the access token and ID token. The mapped number is used in the authentication flow conditions.

Mapping can be also specified at the client level in case that particular client needs to use different values than realm. However, a best practice is to stick to realm mappings.

For further details see Step-up Authentication and the official OIDC specification.

With this workflow, users will have to use an UPDATE_EMAIL action to change their own email address.

The action is associated with a single email input form. If the realm has email verification disabled, this action will allow to update the email without verification. If the realm has email verification enabled, the action will send an email update action token to the new email address without changing the account email. Only the action token triggering will complete the email update.

Applications are able to send their users to the email update form by leveraging UPDATE_EMAIL as an AIA (Application Initiated Action).

We recommend that you regularly rotate keys. Start by creating new keys with a higher priority than the existing active keys. You can instead create new keys with the same priority and making the previous keys passive.

Once new keys are available, all new tokens and cookies will be signed with the new keys. When a user authenticates to an application, the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are signed with the new keys. Eventually, all cookies and tokens use the new keys and after a while the old keys can be removed.

The frequency of deleting old keys is a tradeoff between security and making sure all cookies and tokens are updated. Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys. If a user was inactive in the period between the new keys being added and the old keys being removed, that user will have to re-authenticate.

Rotating keys also applies to offline tokens. To make sure they are updated, the applications need to refresh the tokens before the old keys are removed.

Use this procedure to generate a key pair including a self-signed certificate.

Changing the priority for a provider will not cause the keys to be re-generated, but if you want to change the keysize you can edit the provider and new keys will be generated.

You can rotate keys by extracting a certificate from an RSA generated key pair and using that certificate in a new keystore.

To add a key pair and certificate obtained elsewhere select Providers and choose rsa from the dropdown. You can change the priority to make sure the new key pair becomes the active key pair.

To add a key pair and certificate stored in a Java Keystore file on the host select Providers and choose java-keystore from the dropdown. You can change the priority to make sure the new key pair becomes the active key pair.

For the associated certificate chain to be loaded it must be imported to the Java Keystore file with the same Key Alias used to load the key pair.

Red Hat build of Keycloak has the signing keys stored just locally and they are never shared with the client applications, users or other entities. However, if you think that your realm signing key was compromised, you should first generate new key pair as described above and then immediately remove the compromised key pair.

Alternatively, you can delete the provider from the Providers table.

Pushing the not-before policy ensures that client applications do not accept the existing tokens signed by the compromised key. The client application is forced to download new key pairs from Red Hat build of Keycloak also so the tokens signed by the compromised key will be invalid.

Red Hat build of Keycloak imports users from LDAP into the local Red Hat build of Keycloak user database. This copy of the user database synchronizes on-demand or through a periodic background task. An exception exists for synchronizing passwords. Red Hat build of Keycloak never imports passwords. Password validation always occurs on the LDAP server.

The advantage of synchronization is that all Red Hat build of Keycloak features work efficiently because any required extra per-user data is stored locally. The disadvantage is that each time Red Hat build of Keycloak queries a specific user for the first time, Red Hat build of Keycloak performs a corresponding database insert.

You can synchronize the import with your LDAP server. Import synchronization is unnecessary when LDAP mappers always read particular attributes from the LDAP rather than the database.

You can use LDAP with Red Hat build of Keycloak without importing users into the Red Hat build of Keycloak user database. The LDAP server backs up the common user model that the Red Hat build of Keycloak runtime uses. If LDAP does not support data that a Red Hat build of Keycloak feature requires, that feature will not work. The advantage of this approach is that you do not have the resource usage of importing and synchronizing copies of LDAP users into the Red Hat build of Keycloak user database.

The Import Users switch on the LDAP configuration page controls this storage mode. To import users, toggle this switch to ON.

Users and admins can modify user metadata, users through the Account Console, and administrators through the Admin Console. The Edit Mode configuration on the LDAP configuration page defines the user’s LDAP update privileges.

When you configure a secure connection URL to your LDAP store (for example,ldaps://myhost.com:636), Red Hat build of Keycloak uses SSL to communicate with the LDAP server. Configure a truststore on the Red Hat build of Keycloak server side so that Red Hat build of Keycloak can trust the SSL connection to LDAP - see Configuring a Truststore chapter.

The Use Truststore SPI configuration property is deprecated. It should normally be left as Always.

If you set the Import Users option, the LDAP Provider handles importing LDAP users into the Red Hat build of Keycloak local database. The first time a user logs in or is returned as part of a user query (e.g. using the search field in the admin console), the LDAP provider imports the LDAP user into the Red Hat build of Keycloak database. During authentication, the LDAP password is validated.

If you want to sync all LDAP users into the Red Hat build of Keycloak database, configure and enable the Sync Settings on the LDAP provider configuration page.

Two types of synchronization exist:

The best way to synchronize is to click Synchronize all users when you first create the LDAP provider, then set up periodic synchronization of changed users.

LDAP mappers are listeners triggered by the LDAP Provider. They provide another extension point to LDAP integration. LDAP mappers are triggered when:

When you create an LDAP Federation provider, Red Hat build of Keycloak automatically provides a set of mappers for this provider. This set is changeable by users, who can also develop mappers or update/delete existing ones.

User Attribute mappers that map basic Red Hat build of Keycloak user attributes, such as username, firstname, lastname, and email, to corresponding LDAP attributes. You can extend these and provide your own additional attribute mappings. The Admin Console provides tooltips to help with configuring the corresponding mappers.

When Red Hat build of Keycloak updates a password, Red Hat build of Keycloak sends the password in plain-text format. This action is different from updating the password in the built-in Red Hat build of Keycloak database, where Red Hat build of Keycloak hashes and salts the password before sending it to the database. For LDAP, Red Hat build of Keycloak relies on the LDAP server to hash and salt the password.

By default, LDAP servers such as MSAD, RHDS, or FreeIPA hash and salt passwords. Other LDAP servers such as OpenLDAP or ApacheDS store the passwords in plain-text unless you use the LDAPv3 Password Modify Extended Operation as described in RFC3062. Enable the LDAPv3 Password Modify Extended Operation in the LDAP configuration page. See the documentation of your LDAP server for more details.

For more efficiency when managing LDAP connections and to improve performance when handling multiple connections, you can enable connection pooling. By doing that, when a connection is closed, it will be returned to the pool for future use therefore reducing the cost of creating new connections all the time.

The LDAP connection pool configuration is configured using the following system properties:

For more details, see the Java LDAP Connection Pooling Configuration documentation.

To set any of these properties, you can set the JAVA_OPTS_APPEND environment variable:

export JAVA_OPTS_APPEND=-Dcom.sun.jndi.ldap.connect.pool.initsize=10 -Dcom.sun.jndi.ldap.connect.pool.maxsize=50

It is useful to increase the logging level to TRACE for the category org.keycloak.storage.ldap. With this setting, many logging messages are sent to the server log in the TRACE level, including the logging for all queries to the LDAP server and the parameters, which were used to send the queries. When you are creating any LDAP question on user forum or JIRA, consider attaching the server log with enabled TRACE logging. If it is too big, the good alternative is to include just the snippet from server log with the messages, which were added to the log during the operation, which causes the issues to you.

Creating new LDAP Store for the LDAP storage provider: ...

It shows the configuration of your LDAP provider. Before you are asking the questions or reporting bugs, it will be nice to include this message to show your LDAP configuration. Eventually feel free to replace some config changes, which you do not want to include, with some placeholder values. One example is bindDn=some-placeholder . For connectionUrl, feel free to replace it as well, but it is generally useful to include at least the protocol, which was used (ldap vs ldaps)`. Similarly it can be useful to include the details for configuration of your LDAP mappers, which are displayed with the message like this at the DEBUG level:

Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...

Note those messages are displayed just with the enabled DEBUG logging.

If no more messages appear for connection pooling even after server restart, it can indicate that connection pooling does not work with your LDAP server.

The FreeIPA Container image is available at Quay.io. To set up the FreeIPA server, see the FreeIPA documentation.

The federation provider obtains the data from SSSD using D-BUS. It authenticates the data using PAM.

Red Hat build of Keycloak uses DBus-Java project to communicate at a low level with D-Bus and JNA to authenticate via Operating System Pluggable Authentication Modules (PAM).

Although now Red Hat build of Keycloak contains all the needed libraries to run the SSSD provider, JDK version 21 is needed. Therefore the SSSD provider will only be displayed when the host configuration is correct and JDK 21 is used to run Red Hat build of Keycloak.

After the installation, configure a federated SSSD store.

You can now authenticate against Red Hat build of Keycloak using a FreeIPA/IdM user and credentials.

By default, Red Hat build of Keycloak provides a basic user profile configuration covering some of the most common user attributes:

In Red Hat build of Keycloak, both username and email attributes have a special handling as they are often used to identify, authenticate, and link user accounts. For those attributes, you are limited to changing their settings, and you can not remove them.

As you will see in the following sections, you are free to change the default configuration by bringing your own attributes or changing the settings for any of the available attributes to better fit it to your needs.

In Red Hat build of Keycloak, users are managed through different contexts:

Except for the Administrative context, all other contexts are considered end-user contexts as they are related to user self-service flows.

Knowing these contexts is important to understand where your user profile configuration will take effect when managing users. Regardless of the context where the user is being managed, the same user profile configuration will be used to render UIs and validate attribute values.

As you will see in the following sections, you might restrict certain attributes to be available only from the administrative context and disable them completely for end-users. The other way around is also true if you don’t want administrators to have access to certain user attributes but only the end-user.

By default, Red Hat build of Keycloak will only recognize the attributes defined in your user profile configuration. The server ignores any other attribute not explicitly defined there.

By being strict about which user attributes can be set to your users, as well as how their values are validated, Red Hat build of Keycloak can add another defense barrier to your realm and help you to prevent unexpected attributes and values associated to your users.

That said, user attributes can be categorized as follows:

Although unmanaged attributes are disabled by default, you can configure your realm using different policies to define how they are handled by the server. For that, click on the Realm Settings at the left side menu, click on the General tab, and then choose any of the following options from the Unmanaged Attributes setting:

These policies give you a fine-grained control over how the server will handle unmanaged attributes. You can choose to completely disable or only support unmanaged attributes when managing users through the administrative context.

When unmanaged attributes are enabled (even if partially) you can manage them from the administration console at the Attributes tab in the User Details UI. If the policy is set to Disabled this tab is not available.

As a security recommendation, try to adhere to the most strict policy as much as possible (e.g.: Disabled or Admin can edit) to prevent unexpected attributes (and values) set to your users when they are managing their profile through end-user contexts. Avoid setting the Enabled policy and prefer defining all the attributes that end-users can manage in your user profile configuration, under your control.

As you will see in the following sections, you can also restrict the audience for an attribute by choosing if it should be visible or writable by users and/or administrators.

For unmanaged attributes, the maximum length is 2048 characters. To specify a different minimum or maximum length, change the unmanaged attribute to a managed attribute and add a length validator.

The user profile configuration is managed on a per-realm basis. For that, click on the Realm Settings link on the left side menu and then click on the User Profile tab.

In the Attributes sub-tab you have a list of all managed attributes.

In the Attribute Groups sub-tab you can manage attribute groups. An attribute group allows you to correlate attributes so that they are displayed together when rendering user facing forms.

In the JSON Editor sub-tab you can view and edit the JSON configuration. You can use this tab to grab your current configuration or manage it manually. Any change you make to this tab is reflected in the other tabs, and vice-versa.

In the next section, you are going to learn how to manage attributes.

At the Attributes sub-tab you can create, edit, and delete the managed attributes.

To define a new attribute and associate it with the user profile, click on the Create attribute button at the top of the attribute listing.

When configuring the attribute you can define the following settings:

When you create an attribute, the attribute is only available from administrative contexts to avoid unexpectedly exposing attributes to end-users. Effectively, the attribute won’t be accessible to end-users when they are managing their profile through the end-user contexts. You can change the Permissions settings anytime accordingly to your needs.

You can enable validation to managed attributes to make sure the attribute value conforms to specific rules. For that, you can add or remove validators from the Validations settings when managing an attribute.

Validation happens at any time when writing to an attribute, and they can throw errors that will be shown in UIs when the value fails a validation.

For security reasons, every attribute that is editable by users should have a validation to restrict the size of the values users enter. If no length validator has been specified, Red Hat build of Keycloak defaults to a maximum length of 2048 characters.

In order to pass additional information to frontends, attributes can be decorated with annotations to dictate how attributes are rendered. This capability is mainly useful when extending Red Hat build of Keycloak themes to render pages dynamically based on the annotations associated with attributes.

Annotations are used, for example, for Changing the HTML type for an Attribute and Changing the DOM representation of an Attribute, as you will see in the following sections.

An annotation is a key/value pair shared with the UI so that they can change how the HTML element corresponding to the attribute is rendered. You can set any annotation you want to an attribute as long as the annotation is supported by the theme your realm is using.

"attributes": [
<...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select",
    "inputOptionLabels": {
      "sweng": "Software Engineer",
      "swarch": "Software Architect"
    }
  }
}
...
]

"attributes": [
...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select-radiobuttons",
    "inputOptionLabels": {
      "sweng": "${jobtitle.swengineer}",
      "swarch": "${jobtitle.swarchitect}"
    }
  }
}
...
]

import { registerElementAnnotatedBy } from "./userProfile.js";

registerElementAnnotatedBy({
  name: 'kcMyCustomValidation',
  onAdd(element) {
    var listener = function (event) {
        // do something on keyup
    };

    element.addEventListener("keyup", listener);

    // returns a cleanup function to remove the event listener
    return () => element.removeEventListener("keyup", listener);
  }
});

document.querySelectorAll(`[data-kcMyCustomValidation]`).forEach((element) => {
    var listener = function (evt) {
        // do something on keyup
    };

    element.addEventListener("keyup", listener);
  });

At the Attribute Groups sub-tab you can create, edit, and delete attribute groups. An attribute group allows you to define a container for correlated attributes so that they are rendered together when at the user-facing forms.

To create a new group, click on the Create attributes group button on the top of the attribute groups listing.

When configuring the group you can define the following settings:

The user profile configuration is stored using a well-defined JSON schema. You can choose from editing the user profile configuration directly by clicking on the JSON Editor sub-tab.

The JSON schema is defined as follows:

{
  "unmanagedAttributePolicy": "DISABLED",
  "attributes": [
    {
      "name": "myattribute",
      "multivalued": false,
      "displayName": "My Attribute",
      "group": "personalInfo",
      "required": {
        "roles": [ "user", "admin" ],
        "scopes": [ "foo", "bar" ]
      },
      "permissions": {
        "view": [ "admin", "user" ],
        "edit": [ "admin", "user" ]
      },
      "validations": {
        "email": {
          "max-local-length": 64
        },
        "length": {
          "max": 255
        }
      },
      "annotations": {
        "myannotation": "myannotation-value"
      }
    }
  ],
  "groups": [
    {
      "name": "personalInfo",
      "displayHeader": "Personal Information",
      "annotations": {
        "foo": ["foo-value"],
        "bar": ["bar-value"]
      }
    }
  ]
}

The schema supports as many attributes and groups as you need.

The unmanagedAttributePolicy property defines the unmanaged attribute policy by setting one of following values. For more details, look at the Understanding Managed and Unmanaged Attributes.

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {}
  ]
}

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": ["user"]
      }
  ]
}

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "scopes": ["foo"]
      }
  ]
}

{
  "attributes": [
    {
      "name": "myattribute",
      "permissions": {
        "view": ["admin"],
        "edit": ["user"]
      }
  ]
}

{
  "attributes": [
    {
      "name": "myattribute",
      "annotations": {
        "foo": ["foo-value"],
        "bar": ["bar-value"]
      }
  ]
}

The UIs from all the user profile contexts (including the administration console) are rendered dynamically accordingly to your user profile configuration.

The default rendering mechanism provides the following capabilities:

In order to make sure end-user profiles are in compliance with the configuration, administrators can use the VerifyProfile required action to eventually force users to update their profiles when authenticating to Red Hat build of Keycloak.

When enabled, the VerifyProfile action is going to perform the following steps when the user is authenticating:

The VerifyProfile action is enabled by default. To disable it, click on the Authentication link on the left side menu and then click on the Required Actions tab. At this tab, use the Enabled switch of the VerifyProfile action to disable it.

If you want to use internationalized messages when configuring attributes, attributes groups, and annotations, you can set their display name, description, and values, using a placeholder that will translate to a message from a message bundle.

For that, you can use a placeholder to resolve messages keys such as ${myAttributeName}, where myAttributeName is the key for a message in a message bundle. For more details, look at Server Developer Guide about how to add message bundles to custom themes.

If a user does not have a password, or if the password has been deleted, the Set Password section is displayed.

If a user already has a password, it can be reset in the Reset Password section.

You can also request that the user reset the password.

If OTP is conditional in your realm, the user must navigate to Red Hat build of Keycloak Account Console to reconfigure a new OTP generator. If OTP is required, then the user must reconfigure a new OTP generator when logging in.

Alternatively, you can send an email to the user that requests the user reset the OTP generator. The following procedure also applies if the user already has an OTP credential.

Enable users to self-register.

After you enable this setting, a Register link displays on the login page of the Admin Console.

As a new user, you must complete a registration form to log in for the first time. You add profile information and a password to register.

For a user to register, you can require agreement to your terms and conditions.

You can set the actions that are required for any user.

You can specify what actions are required before the first login of all new users. The requirements apply to a user created by the Add User button on the Users page or the Register link on the login page.

You can enable a required action that new users must accept the terms and conditions before logging in to Red Hat build of Keycloak for the first time.

In case the user is already authenticated due to an active SSO session, that user usually does not need to actively re-authenticate. However, if that user actively authenticated longer than five minutes ago, the client can still request re-authentication when some AIA is requested. Exceptions exist from this guideline as follows:

Some AIA can require the parameter to be sent together with the action name. For instance, the Delete Credential action can be triggered only by AIA and it requires a parameter to be sent together with the name of the action, which points to the ID of the removed credential. So the URL for this example would be kc_action=delete_credential:ce1008ac-f811-427f-825a-c0b878d1c24b. In this case, the part after the colon character (ce1008ac-f811-427f-825a-c0b878d1c24b) contains the ID of the credential of the particular user, which is to be deleted. The Delete Credential action displays the confirmation screen where the user can confirm agreement to delete the credential.

To see all available actions, log in to the Admin Console and go to the top right top corner to click Realm info → tab Provider info → Find provider required-action . But note that this can be further restricted based on what actions are enabled for your realm in the Required actions tab.

You enable this capability on the Required Actions tab.

You can give specific users a role that allows account deletion.

Once you have the delete-account role, you can delete your own account.

You can sign out all users in the realm. From the Action list, select Sign out all active sessions. All SSO cookies become invalid. Red Hat build of Keycloak notifies clients by using the Red Hat build of Keycloak OIDC client adapter of the logout event. Clients requesting authentication within active browser sessions must log in again. Client types such as SAML do not receive a back-channel logout request.

Groups and roles have some similarities and differences. In Red Hat build of Keycloak, groups are a collection of users to which you apply roles and attributes. Roles define types of users, and applications assign permissions and access control to roles.

Composite Roles are similar to Groups as they provide the same functionality. The difference between them is conceptual. Composite roles apply the permission model to a set of services and applications. Use composite roles to manage applications and services.

Groups focus on collections of users and their roles in an organization. Use groups to manage users.

To automatically assign group membership to any users who is created or who is imported through Identity Brokering, you use default groups.

This screenshot shows that some default groups already exist.

The algorithms available in Red Hat build of Keycloak for your OTP generators are time-based and counter-based.

With Time-Based One Time Passwords (TOTP), the token generator will hash the current time and a shared secret. The server validates the OTP by comparing the hashes within a window of time to the submitted value. TOTPs are valid for a short window of time.

With Counter-Based One Time Passwords (HOTP), Red Hat build of Keycloak uses a shared counter rather than the current time. The Red Hat build of Keycloak server increments the counter with each successful OTP login. Valid OTPs change after a successful login.

TOTP is more secure than HOTP because the matchable OTP is valid for a short window of time, while the OTP for HOTP is valid for an indeterminate amount of time. HOTP is more user-friendly than TOTP because no time limit exists to enter the OTP.

HOTP requires a database update every time the server increments the counter. This update is a performance drain on the authentication server during heavy load. To increase efficiency, TOTP does not remember passwords used, so there is no need to perform database updates. The drawback is that it is possible to reuse TOTPs in the valid time interval.

Red Hat build of Keycloak has several built-in flows. You cannot modify these flows, but you can alter the flow’s requirements to suit your needs.

Important functionality and security considerations apply when you design a flow.

To create a flow, perform the following:

When creating a new flow, you must create a top-level flow first with the following options:

When Red Hat build of Keycloak has created the flow, Red Hat build of Keycloak displays the Add step, and Add sub-flow buttons.

Three factors determine the behavior of flows and sub-flows.

Executions have a wide variety of actions, from sending a reset email to validating an OTP. Add executions with the Add step button.

Authentication executions can optionally have a reference value configured. This can be utilized by the Authentication Method Reference (AMR) protocol mapper to populate the amr claim in OIDC access and ID tokens (for more information on the AMR claim, see RFC-8176). When the Authentication Method Reference (AMR) protocol mapper is configured for a client, it will populate the amr claim with the reference value for any authenticator execution the user successfully completes during the authentication flow.

Two types of executions exist, automatic executions and interactive executions. Automatic executions are similar to the Cookie execution and will automatically perform their action in the flow. Interactive executions halt the flow to get input. Executions executing successfully set their status to success. For a flow to complete, it needs at least one execution with a status of success.

You can add sub-flows to top-level flows with the Add sub-flow button. The Add sub-flow button displays the Create Execution Flow page. This page is similar to the Create Top Level Form page. The difference is that the Flow Type can be basic (default) or form. The form type constructs a sub-flow that generates a form for the user, similar to the built-in Registration flow. Sub-flows success depends on how their executions evaluate, including their contained sub-flows. See the execution requirements section for an in-depth explanation of how sub-flows work.

All elements in a flow have a Delete option next to the element. Some executions have a ⚙️ menu item (the gear icon) to configure the execution. It is also possible to add executions and sub-flows to sub-flows with the Add step and Add sub-flow links.

Since the order of execution is important, you can move executions and sub-flows up and down by dragging their names.

To illustrate the creation of flows, this section describes creating an advanced browser login flow. The purpose of this flow is to allow a user a choice between logging in using a password-less manner with WebAuthn, or two-factor authentication with a password and OTP.

At this stage, the form requires a username but no password. We must enable password authentication to avoid security risks.

Finally, change the bindings.

After entering the username, the flow works as follows:

If users have WebAuthn passwordless credentials recorded, they can use these credentials to log in directly. This is the password-less login. The user can also select Password with OTP because the WebAuthn Passwordless execution and the Password with OTP flow are set to Alternative. If they are set to Required, the user has to enter WebAuthn, password, and OTP.

If the user selects the Try another way link with WebAuthn passwordless authentication, the user can choose between Password and Passkey (WebAuthn passwordless). When selecting the password, the user will need to continue and log in with the assigned OTP. If the user has no WebAuthn credentials, the user must enter the password and then the OTP. If the user has no OTP credential, they will be asked to record one.

This section describes how to create advanced browser login flow using the step-up mechanism. The purpose of step-up authentication is to allow access to clients or resources based on a specific authentication level of a user.

Now you configure the flow for the first authentication level.

Now you configure the flow for the second authentication level.

Finally, change the bindings.

https://{DOMAIN}/realms/{REALMNAME}/protocol/openid-connect/auth?client_id={CLIENT-ID}&redirect_uri={REDIRECT-URI}&scope=openid&response_type=code&response_mode=query&nonce=exg16fxdjcu&claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22gold%22%5D%7D%7D%7D

The claims parameter is specified in a JSON representation:

claims= {
            "id_token": {
                "acr": {
                    "essential": true,
                    "values": ["gold"]
                }
            }
        }

The Red Hat build of Keycloak javascript adapter has support for easy construct of this JSON and sending it in the login request. See Keycloak JavaScript adapter in the securing apps section for more details.

You can also use simpler parameter acr_values instead of claims parameter to request particular levels as non-essential. This is mentioned in the OIDC specification.

You can also configure the default level for the particular client, which is used when the parameter acr_values or the parameter claims with the acr claim is not present. For further details, see Client ACR configuration).

For more details see the official OIDC specification.

Flow logic

The logic for the previous configured authentication flow is as follows:
If a client request a high authentication level, meaning Level of Authentication 2 (LoA 2), a user has to perform full 2-factor authentication: Username/Password + OTP. However, if a user already has a session in Red Hat build of Keycloak, that was logged in with username and password (LoA 1), the user is only asked for the second authentication factor (OTP).

The option Max Age in the condition determines how long (how much seconds) the subsequent authentication level is valid. This setting helps to decide whether the user will be asked to present the authentication factor again during a subsequent authentication. If the particular level X is requested by the claims or acr_values parameter and user already authenticated with level X, but it is expired (for example max age is configured to 300 and user authenticated before 310 seconds) then the user will be asked to re-authenticate again with the particular level. However if the level is not yet expired, the user will be automatically considered as authenticated with that level.

Using Max Age with the value 0 means, that particular level is valid just for this single authentication. Hence every re-authentication requesting that level will need to authenticate again with that level. This is useful for operations that require higher security in the application (e.g. send payment) and always require authentication with the specific level.

If no explicit level is requested by parameters, the Red Hat build of Keycloak will require the authentication with the first LoA condition found in the authentication flow, such as the Username/Password in the preceding example. When a user was already authenticated with that level and that level expired, the user is not required to re-authenticate, but acr in the token will have the value 0. This result is considered as authentication based solely on long-lived browser cookie as mentioned in the section 2 of OIDC Core 1.0 specification.

Example scenario

ACR claim in the token

ACR claim is added to the token by the acr loa level protocol mapper defined in the acr client scope. This client scope is the realm default client scope and hence will be added to all newly created clients in the realm.

In case you do not want acr claim inside tokens or you need some custom logic for adding it, you can remove the client scope from your client.

Note when the login request initiates a request with the claims parameter requesting acr as essential claim, then Red Hat build of Keycloak will always return one of the specified levels. If it is not able to return one of the specified levels (For example if the requested level is unknown or bigger than configured conditions in the authentication flow), then Red Hat build of Keycloak will throw an error.

Usually when the user is redirected to the Red Hat build of Keycloak from client application, the browser flow is triggered. This flow may allow the user to register in case that realm registration is enabled and the user clicks Register on the login screen. Also, if Forget password is enabled for the realm, the user can click Forget password on the login screen, which triggers the Reset credentials flow where users can reset credentials after email address confirmation.

Sometimes it can be useful for the client application to directly redirect the user to the Registration screen or to the Reset credentials flow. The resulting action will match the action of when the user clicks Register or Forget password on the normal login screen. Automatic redirect to the registration or reset-credentials screen can be done as follows:

The steps to set up a Kerberos server depends on the operating system (OS) and the Kerberos vendor. Consult Windows Active Directory, MIT Kerberos, and your OS documentation for instructions on setting up and configuring a Kerberos server.

During setup, perform these steps:

sudo kadmin.local

Then, add HTTP principal and export its key to a keytab file with commands such as:

addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG

Ensure the keytab file /tmp/http.keytab is accessible on the host where Red Hat build of Keycloak is running.

Install a Kerberos client on your machine.

Client machines must have a Kerberos client and set up the krb5.conf as described above. The client machines must also enable SPNEGO login support in their browser. See configuring Firefox for Kerberos if you are using the Firefox browser.

The .mydomain.org URI must be in the network.negotiate-auth.trusted-uris configuration option.

In Windows domains, clients do not need to adjust their configuration. Internet Explorer and Edge can already participate in SPNEGO authentication.

Kerberos supports the credential delegation. Applications may need access to the Kerberos ticket so they can reuse it to interact with other services secured by Kerberos. Because the Red Hat build of Keycloak server processed the SPNEGO protocol, you must propagate the GSS credential to your application within the OpenID Connect token claim or a SAML assertion attribute. Red Hat build of Keycloak transmits this to your application from the Red Hat build of Keycloak server. To insert this claim into the token or assertion, each application must enable the built-in protocol mapper gss delegation credential. This mapper is available in the Mappers tab of the application’s client page. See Protocol Mappers chapter for more details.

Applications must deserialize the claim it receives from Red Hat build of Keycloak before using it to make GSS calls against other services. When you deserialize the credential from the access token to the GSSCredential object, create the GSSContext with this credential passed to the GSSManager.createContext method. For example:

// Obtain accessToken in your application.
KeycloakPrincipal keycloakPrincipal = (KeycloakPrincipal) servletReq.getUserPrincipal();
AccessToken accessToken = keycloakPrincipal.getKeycloakSecurityContext().getToken();

// Retrieve Kerberos credential from accessToken and deserialize it
String serializedGssCredential = (String) accessToken.getOtherClaims().
    get(org.keycloak.common.constants.KerberosConstants.GSS_DELEGATION_CREDENTIAL);

GSSCredential deserializedGssCredential = org.keycloak.common.util.KerberosSerializationUtils.
    deserializeCredential(serializedGssCredential);

// Create GSSContext to call other Kerberos-secured services
GSSContext context = gssManager.createContext(serviceName, krb5Oid,
    deserializedGssCredential, GSSContext.DEFAULT_LIFETIME);

In the Kerberos protocol, the realm is a set of Kerberos principals. The definition of these principals exists in the Kerberos database, which is typically an LDAP server.

The Kerberos protocol allows cross-realm trust. For example, if 2 Kerberos realms, A and B, exist, then cross-realm trust will allow the users from realm A to access realm B’s resources. Realm B trusts realm A.

The Red Hat build of Keycloak server supports cross-realm trust. To implement this, perform the following:

Finding users is based on the LDAP storage provider option Kerberos principal attribute. When this is configured for instance with value like userPrincipalName, then after SPNEGO authentication of user john@A, Red Hat build of Keycloak will try to lookup LDAP user with attribute userPrincipalName equivalent to john@A. If Kerberos principal attribute is left empty, then Red Hat build of Keycloak will lookup the LDAP user based on the prefix of his kerberos principal with the realm omitted. For example, Kerberos principal user john@A must be available in the LDAP under username john, so typically under an LDAP DN such as uid=john,ou=People,dc=example,dc=com. If you want users from realm A and B to authenticate, ensure that LDAP can find users from both realms A and B.

Users from multiple Kerberos realms are allowed to authenticate as every user would have attribute KERBEROS_PRINCIPAL referring to the kerberos principal used for authentication and this is used for further lookups of this user. To avoid conflicts when there is user john in both kerberos realms A and B, the username of the Red Hat build of Keycloak user might contain the kerberos realm lowercased. For instance username would be john@a. Just in case when realm matches with the configured Kerberos realm, the realm suffix might be omitted from the generated username. For instance username would be john for the Kerberos principal john@A as long as the Kerberos realm is configured on the Kerberos provider is A.

If you have issues, enable additional logging to debug the problem:

Supported Certificate Identity Sources:

emailAddress=(.*?)(?:,|$)

The setup procedure of WebAuthn support for 2FA is the following:

If you require WebAuthn for all users:

Users can log in with WebAuthn if they have a WebAuthn credential registered only. So instead of adding the WebAuthn Authenticator execution, you can:

The user can choose between using WebAuthn and OTP for the second factor:

After registering a WebAuthn authenticator, the user carries out the following operations:

When registering a WebAuthn authenticator, Red Hat build of Keycloak verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. Red Hat build of Keycloak requires the trust anchor’s certificates imported into the truststore.

To omit this validation, disable this truststore or set the WebAuthn policy’s configuration item "Attestation Conveyance Preference" to "none".

Red Hat build of Keycloak uses WebAuthn for two-factor authentication, but you can use WebAuthn as the first-factor authentication. In this case, users with passwordless WebAuthn credentials can authenticate to Red Hat build of Keycloak without a password. Red Hat build of Keycloak can use WebAuthn as both the passwordless and two-factor authentication mechanism in the context of a realm and a single authentication flow.

An administrator typically requires that Passkeys registered by users for the WebAuthn passwordless authentication meet different requirements. For example, the Passkeys may require users to authenticate to the Passkey using a PIN, or the Passkey attests with a stronger certificate authority.

Because of this, Red Hat build of Keycloak permits administrators to configure a separate WebAuthn Passwordless Policy. There is a required Webauthn Register Passwordless action of type and separate authenticator of type WebAuthn Passwordless Authenticator.

Red Hat build of Keycloak uses WebAuthn for two-factor authentication, but you can use WebAuthn as the first-factor authentication. In this case, users with passwordless WebAuthn credentials can authenticate to Red Hat build of Keycloak without submitting a login or a password. Red Hat build of Keycloak can use WebAuthn as both the loginless/passwordless and two-factor authentication mechanism in the context of a realm.

An administrator typically requires that Passkeys registered by users for the WebAuthn loginless authentication meet different requirements. Loginless authentication requires users to authenticate to the Passkey (for example by using a PIN code or a fingerprint) and that the cryptographic keys associated with the loginless credential are stored physically on the Passkey. Not all Passkeys meet that kind of requirement. Check with your Passkey vendor if your device supports 'user verification' and 'discoverable credential'. See Supported Passkeys.

Red Hat build of Keycloak permits administrators to configure the WebAuthn Passwordless Policy in a way that allows loginless authentication. Note that loginless authentication can only be configured with WebAuthn Passwordless Policy and with WebAuthn Passwordless credentials. WebAuthn loginless authentication and WebAuthn passwordless authentication can be configured on the same realm but will share the same policy WebAuthn Passwordless Policy.

Passkey Authentication with Conditional UI can authenticate a user with its passkey in the same way as in LoginLess WebAuthn. This authentication shows a user a list of passkeys stored on a device where the user runs a browser. Therefore, the user can select one of the passkeys in the list to authenticate them. Compared with LoginLess WebAuthn, the authentication improves the user’s experience of authentication.

You can allow or deny access to resources in a conditional flow. The two authenticators Deny Access and Allow Access control access to the resources by conditions.

Here is an example how to deny access to all users who do not have the role role1 and show an error message defined by a property deny-role1. This example includes Condition - User Role and Deny Access executions.

The last thing is defining the property with an error message in the login theme messages_en.properties (for English):

deny-role1 = You do not have required role!

As described in the previous section, a situation can involve a user who is trying to authenticate to the Red Hat build of Keycloak server from multiple tabs of a single browser. However, when that user authenticates in one browser tab, the other browser tabs will automatically restart the authentication. This authentication occurs due to the small javascript available on the Red Hat build of Keycloak login pages. The restart will typically authenticate the user in other browser tabs and redirect to clients because there is an SSO session now due to the fact that the user just successfully authenticated in first browser tab. Some rare exceptions exist when a user is not automatically authenticated in other browser tabs, such as for instance when using an OIDC parameter prompt=login or step-up authentication requesting a stronger authentication factor than the currently authenticated factor.

In some rare cases, it can happen that after authentication in the first browser tab, other browser tabs are not able to restart authentication because the authentication session is already expired. In this case, the particular browser tab will redirect the error about the expired authentication session back to the client in a protocol specific way. For more details, see the corresponding sections of OIDC documentation in the securing apps section. When the client application receives such an error, it can immediately resubmit the OIDC/SAML authentication request to Red Hat build of Keycloak as this should usually automatically authenticate the user due to the existing SSO session as described earlier. As a result, the end user is authenticated automatically in all browser tabs. The Keycloak JavaScript adapter in the securing apps section, and Red Hat build of Keycloak Identity provider support to handle this error automatically and retry the authentication to the Red Hat build of Keycloak server in such a case.

To log in with Bitbucket, perform the following procedure.

Red Hat build of Keycloak sends profile requests to graph.facebook.com/me?fields=id,name,email,first_name,last_name by default. The response contains the id, name, email, first_name, and last_name fields only. To fetch additional fields from the Facebook profile, add a corresponding scope and add the field name in the Additional user’s profile fields configuration option field.

To log in with GitHub, perform the following procedure.