Chapter 8. Configuring authentication
Chapter 8. Configuring authentication This chapter covers several authentication topics. These topics include: Enforcing strict password and One Time Password (OTP) policies. Managing different credential types. Logging in with Kerberos. Disabling and enabling built-in credential types. 8.1. Password policies When Red Hat build of Keycloak creates a realm, it does not associate password policies with the realm. You can set a simple password with no restrictions on its length, security, or complexity. Simple passwords are unacceptable in production environments. Red Hat build of Keycloak has a set of password policies available through the Admin Console. Procedure Click Authentication in the menu. Click the Policies tab. Select the policy to add in the Add policy drop-down box. Enter a value that applies to the policy chosen. Click Save . Password policy After saving the policy, Red Hat build of Keycloak enforces the policy for new users. Note The new policy will not be effective for existing users. Therefore, make sure that you set the password policy from the beginning of the realm creation or add "Update password" to existing users or use "Expire password" to make sure that users update their passwords in "N" days, which will actually adjust to new password policies. 8.1.1. Password policy types 8.1.1.1. HashAlgorithm Passwords are not stored in cleartext. Before storage or validation, Red Hat build of Keycloak hashes passwords using standard hashing algorithms. Supported password hashing algorithms are shown in the following table. Hashing algorithm Description argon2 Argon2 (default for non-FIPS deployments) pbkdf2-sha512 PBKDF2 with SHA512 (default for FIPS deployments) pbkdf2-sha256 PBKDF2 with SHA256 pbkdf2 PBKDF2 with SHA1 (deprecated) It is highly recommended to use Argon2 when possible as it has significantly less CPU requirements compared to PBKDF2, while at the same time being more secure. The default password hashing algorithm for the server can be configured with --spi-password-hashing-provider-default=<algorithm> . To prevent excessive memory and CPU usage, the parallel computation of hashes by Argon2 is by default limited to the number of cores available to the JVM. To configure the Argon2 hashing provider, use its provider options. See the Server Developer Guide on how to add your own hashing algorithm. Note If you change the hashing algorithm, password hashes in storage will not change until the user logs in. 8.1.1.2. Hashing iterations Specifies the number of times Red Hat build of Keycloak hashes passwords before storage or verification. The default value is -1, which uses the default hashing iterations for the selected hashing algorithm as listed in the following table. Hashing algorithm Default hash iterations argon2 5 pbkdf2-sha512 210,000 pbkdf2-sha256 600,000 pbkdf2 1,300,000 Note In most cases the hashing iterations should not be changed from the recommended default values. Lower values for iterations provide insufficient security, while higher values result in higher CPU power requirements. 8.1.1.3. Digits The number of numerical digits required in the password string. 8.1.1.4. Lowercase characters The number of lower case letters required in the password string. 8.1.1.5. Uppercase characters The number of upper case letters required in the password string. 8.1.1.6. Special characters The number of special characters required in the password string. 8.1.1.7. Not username The password cannot be the same as the username. 8.1.1.8. Not email The password cannot be the same as the email address of the user. 8.1.1.9. Regular expression Password must match one or more defined Java regular expression patterns. See Java's regular expression documentation for the syntax of those expressions. 8.1.1.10. Expire password The number of days the password is valid. When the number of days has expired, the user must change their password. 8.1.1.11. Not recently used Password cannot be already used by the user. Red Hat build of Keycloak stores a history of used passwords. The number of old passwords stored is configurable in Red Hat build of Keycloak. 8.1.1.12. Not recently used (In Days) Password cannot be reused within the configured time period (in days). If the new password was last set within this period, the user will be forced to provide a different one. 8.1.1.13. Password blacklist Password must not be in a blacklist file. Blacklist files are UTF-8 plain-text files with Unix line endings. Every line represents a blacklisted password. Red Hat build of Keycloak compares passwords in a case-insensitive manner. The value of the blacklist file must be the name of the blacklist file, for example, 100k_passwords.txt . Blacklist files resolve against USD{kc.home.dir}/data/password-blacklists/ by default. Customize this path using: The keycloak.password.blacklists.path system property. The blacklistsPath property of the passwordBlacklist policy SPI configuration. To configure the blacklist folder using the CLI, use --spi-password-policy-password-blacklist-blacklists-path=/path/to/blacklistsFolder . A note about False Positives The current implementation uses a BloomFilter for fast and memory efficient containment checks, such as whether a given password is contained in a blacklist, with the possibility for false positives. By default a false positive probability of 0.01% is used. To change the false positive probability by CLI configuration, use --spi-password-policy-password-blacklist-false-positive-probability=0.00001 . 8.1.1.14. Maximum Authentication Age Specifies the maximum age of a user authentication in seconds with which the user can update a password without re-authentication. A value of 0 indicates that the user has to always re-authenticate with their current password before they can update the password. See AIA section for some additional details about this policy. Note The Maximum Authentication Age is configurable also when configuring the required action Update Password in the Required Actions tab in the Admin Console. The better choice is to use the required action for the configuration because the Maximum Authentication Age password policy might be deprecated/removed in the future. 8.2. One Time Password (OTP) policies Red Hat build of Keycloak has several policies for setting up a FreeOTP or Google Authenticator One-Time Password generator. Procedure Click Authentication in the menu. Click the Policy tab. Click the OTP Policy tab. Otp Policy Red Hat build of Keycloak generates a QR code on the OTP set-up page, based on information configured in the OTP Policy tab. FreeOTP and Google Authenticator scan the QR code when configuring OTP. 8.2.1. Time-based or counter-based one time passwords 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. 8.2.2. TOTP configuration options 8.2.2.1. OTP hash algorithm The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512. 8.2.2.2. Number of digits The length of the OTP. Short OTPs are user-friendly, easier to type, and easier to remember. Longer OTPs are more secure than shorter OTPs. 8.2.2.3. Look around window The number of intervals the server attempts to match the hash. This option is present in Red Hat build of Keycloak if the clock of the TOTP generator or authentication server becomes out-of-sync. The default value of 1 is adequate. For example, if the time interval for a token is 30 seconds, the default value of 1 means it will accept valid tokens in the 90-second window (time interval 30 seconds + look ahead 30 seconds + look behind 30 seconds). Every increment of this value increases the valid window by 60 seconds (look ahead 30 seconds + look behind 30 seconds). 8.2.2.4. OTP token period The time interval in seconds the server matches a hash. Each time the interval passes, the token generator generates a TOTP. 8.2.2.5. Reusable code Determine whether OTP tokens can be reused in the authentication process or user needs to wait for the token. Users cannot reuse those tokens by default, and the administrator needs to explicitly specify that those tokens can be reused. 8.2.3. HOTP configuration options 8.2.3.1. OTP hash algorithm The default algorithm is SHA1. The other, more secure options are SHA256 and SHA512. 8.2.3.2. Number of digits The length of the OTP. Short OTPs are user-friendly, easier to type, and easier to remember. Longer OTPs are more secure than shorter OTPs. 8.2.3.3. Look around window The number of and following intervals the server attempts to match the hash. This option is present in Red Hat build of Keycloak if the clock of the TOTP generator or authentication server become out-of-sync. The default value of 1 is adequate. This option is present in Red Hat build of Keycloak to cover when the user's counter gets ahead of the server. 8.2.3.4. Initial counter The value of the initial counter. 8.3. Authentication flows An authentication flow is a container of authentications, screens, and actions, during log in, registration, and other Red Hat build of Keycloak workflows. 8.3.1. Built-in flows 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. Procedure Click Authentication in the menu. Click on the Browser item in the list to see the details. Browser flow 8.3.1.1. Auth type The name of the authentication or the action to execute. If an authentication is indented, it is in a sub-flow. It may or may not be executed, depending on the behavior of its parent. Cookie The first time a user logs in successfully, Red Hat build of Keycloak sets a session cookie. If the cookie is already set, this authentication type is successful. Since the cookie provider returned success and each execution at this level of the flow is alternative , Red Hat build of Keycloak does not perform any other execution. This results in a successful login. Kerberos This authenticator is disabled by default and is skipped during the Browser Flow. Identity Provider Redirector This action is configured through the Actions > Config link. It redirects to another IdP for identity brokering . Forms Since this sub-flow is marked as alternative , it will not be executed if the Cookie authentication type passed. This sub-flow contains an additional authentication type that needs to be executed. Red Hat build of Keycloak loads the executions for this sub-flow and processes them. The first execution is the Username Password Form , an authentication type that renders the username and password page. It is marked as required , so the user must enter a valid username and password. The second execution is the Browser - Conditional OTP sub-flow. This sub-flow is conditional and executes depending on the result of the Condition - User Configured execution. If the result is true, Red Hat build of Keycloak loads the executions for this sub-flow and processes them. The execution is the Condition - User Configured authentication. This authentication checks if Red Hat build of Keycloak has configured other executions in the flow for the user. The Browser - Conditional OTP sub-flow executes only when the user has a configured OTP credential. The final execution is the OTP Form . Red Hat build of Keycloak marks this execution as required but it runs only when the user has an OTP credential set up because of the setup in the conditional sub-flow. If not, the user does not see an OTP form. 8.3.1.2. Requirement A set of radio buttons that control the execution of an action executes. 8.3.1.2.1. Required All Required elements in the flow must be successfully sequentially executed. The flow terminates if a required element fails. 8.3.1.2.2. Alternative Only a single element must successfully execute for the flow to evaluate as successful. Because the Required flow elements are sufficient to mark a flow as successful, any Alternative flow element within a flow containing Required flow elements will not execute. 8.3.1.2.3. Disabled The element does not count to mark a flow as successful. 8.3.1.2.4. Conditional This requirement type is only set on sub-flows. A Conditional sub-flow contains executions. These executions must evaluate to logical statements. If all executions evaluate as true , the Conditional sub-flow acts as Required . If any executions evaluate as false , the Conditional sub-flow acts as Disabled . If you do not set an execution, the Conditional sub-flow acts as Disabled . If a flow contains executions and the flow is not set to Conditional , Red Hat build of Keycloak does not evaluate the executions, and the executions are considered functionally Disabled . 8.3.2. Creating flows Important functionality and security considerations apply when you design a flow. To create a flow, perform the following: Procedure Click Authentication in the menu. Click Create flow . Note You can copy and then modify an existing flow. Click the "Action list" (the three dots at the end of the row), click Duplicate , and enter a name for the new flow. When creating a new flow, you must create a top-level flow first with the following options: Name The name of the flow. Description The description you can set to the flow. Top-Level Flow Type The type of flow. The type client is used only for the authentication of clients (applications). For all other cases, choose basic . Create a top-level flow When Red Hat build of Keycloak has created the flow, Red Hat build of Keycloak displays the Add step , and Add sub-flow buttons. An empty new flow Three factors determine the behavior of flows and sub-flows. The structure of the flow and sub-flows. The executions within the flows The requirements set within the sub-flows and the executions. Executions have a wide variety of actions, from sending a reset email to validating an OTP. Add executions with the Add step button. Adding an authentication execution 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. Adding an authenticator reference value 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. Note After adding an execution, check the requirement has the correct value. All elements in a flow have a Delete option to the element. Some executions have a ⚙\ufe0f 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. Warning Make sure to properly test your configuration when you configure the authentication flow to confirm that no security holes exist in your setup. We recommend that you test various corner cases. For example, consider testing the authentication behavior for a user when you remove various credentials from the user's account before authentication. As an example, when 2nd-factor authenticators, such as OTP Form or WebAuthn Authenticator, are configured in the flow as REQUIRED and the user does not have credential of particular type, the user will be able to set up the particular credential during authentication itself. This situation means that the user does not authenticate with this credential as he set up it right during the authentication. So for browser authentication, make sure to configure your authentication flow with some 1st-factor credentials such as Password or WebAuthn Passwordless Authenticator. 8.3.3. Creating a password-less browser login flow 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. Procedure Click Authentication in the menu. Click the Flows tab. Click Create flow . Enter Browser Password-less as a name. Click Create . Click Add execution . Select Cookie from the list. Click Add . Select Alternative for the Cookie authentication type to set its requirement to alternative. Click Add step . Select Kerberos from the list. Click Add . Click Add step . Select Identity Provider Redirector from the list. Click Add . Select Alternative for the Identity Provider Redirector authentication type to set its requirement to alternative. Click Add sub-flow . Enter Forms as a name. Click Add . Select Alternative for the Forms authentication type to set its requirement to alternative. The common part with the browser flow Click + menu of the Forms execution. Select Add step . Select Username Form from the list. Click Add . At this stage, the form requires a username but no password. We must enable password authentication to avoid security risks. Click + menu of the Forms sub-flow. Click Add sub-flow . Enter Authentication as name. Click Add . Select Required for the Authentication authentication type to set its requirement to required. Click + menu of the Authentication sub-flow. Click Add step . Select WebAuthn Passwordless Authenticator from the list. Click Add . Select Alternative for the Webauthn Passwordless Authenticator authentication type to set its requirement to alternative. Click + menu of the Authentication sub-flow. Click Add sub-flow . Enter Password with OTP as name. Click Add . Select Alternative for the Password with OTP authentication type to set its requirement to alternative. Click + menu of the Password with OTP sub-flow. Click Add step . Select Password Form from the list. Click Add . Select Required for the Password Form authentication type to set its requirement to required. Click + menu of the Password with OTP sub-flow. Click Add step . Select OTP Form from the list. Click Add . Click Required for the OTP Form authentication type to set its requirement to required. Finally, change the bindings. Click the Action menu at the top of the screen. Select Bind flow from the menu. Click the Browser Flow drop-down list. Click Save . A password-less browser login 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. Note Since the WebAuthn Passwordless execution is set to Alternative rather than Required , this flow will never ask the user to register a WebAuthn credential. For a user to have a Webauthn credential, an administrator must add a required action to the user. Do this by: Enabling the Webauthn Register Passwordless required action in the realm (see the WebAuthn documentation). Setting the required action using the Credential Reset part of a user's Credentials management menu. Creating an advanced flow such as this can have side effects. For example, if you enable the ability to reset the password for users, this would be accessible from the password form. In the default Reset Credentials flow, users must enter their username. Since the user has already entered a username earlier in the Browser Password-less flow, this action is unnecessary for Red Hat build of Keycloak and suboptimal for user experience. To correct this problem, you can: Duplicate the Reset Credentials flow. Set its name to Reset Credentials for password-less , for example. Click Delete (trash icon) of the Choose user step. In the Action menu, select Bind flow and select Reset credentials flow from the dropdown and click Save 8.3.4. Creating a browser login flow with step-up mechanism 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. Procedure Click Authentication in the menu. Click the Flows tab. Click Create flow . Enter Browser Incl Step up Mechanism as a name. Click Save . Click Add execution . Select Cookie from the list. Click Add . Select Alternative for the Cookie authentication type to set its requirement to alternative. Click Add sub-flow . Enter Auth Flow as a name. Click Add . Click Alternative for the Auth Flow authentication type to set its requirement to alternative. Now you configure the flow for the first authentication level. Click + menu of the Auth Flow . Click Add sub-flow . Enter 1st Condition Flow as a name. Click Add . Click Conditional for the 1st Condition Flow authentication type to set its requirement to conditional. Click + menu of the 1st Condition Flow . Click Add condition . Select Conditional - Level Of Authentication from the list. Click Add . Click Required for the Conditional - Level Of Authentication authentication type to set its requirement to required. Click ⚙\ufe0f (gear icon). Enter Level 1 as an alias. Enter 1 for the Level of Authentication (LoA). Set Max Age to 36000 . This value is in seconds and it is equivalent to 10 hours, which is the default SSO Session Max timeout set in the realm. As a result, when a user authenticates with this level, subsequent SSO logins can reuse this level and the user does not need to authenticate with this level until the end of the user session, which is 10 hours by default. Click Save Configure the condition for the first authentication level Click + menu of the 1st Condition Flow . Click Add step . Select Username Password Form from the list. Click Add . Now you configure the flow for the second authentication level. Click + menu of the Auth Flow . Click Add sub-flow . Enter 2nd Condition Flow as an alias. Click Add . Click Conditional for the 2nd Condition Flow authentication type to set its requirement to conditional. Click + menu of the 2nd Condition Flow . Click Add condition . Select Conditional - Level Of Authentication from the item list. Click Add . Click Required for the Conditional - Level Of Authentication authentication type to set its requirement to required. Click ⚙\ufe0f (gear icon). Enter Level 2 as an alias. Enter 2 for the Level of Authentication (LoA). Set Max Age to 0 . As a result, when a user authenticates, this level is valid just for the current authentication, but not any subsequent SSO authentications. So the user will always need to authenticate again with this level when this level is requested. Click Save Configure the condition for the second authentication level Click + menu of the 2nd Condition Flow . Click Add step . Select OTP Form from the list. Click Add . Click Required for the OTP Form authentication type to set its requirement to required. Finally, change the bindings. Click the Action menu at the top of the screen. Select Bind flow from the list. Select Browser Flow in the dropdown. Click Save . Browser login with step-up mechanism Request a certain authentication level To use the step-up mechanism, you specify a requested level of authentication (LoA) in your authentication request. The claims parameter is used for this purpose: The claims parameter is specified in a JSON representation: 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 ). Note To request the acr_values as text (such as gold ) instead of a numeric value, you configure the mapping between the ACR and the LoA. It is possible to configure it at the realm level (recommended) or at the client level. For configuration see ACR to LoA Mapping . For more details see the official OIDC specification . Flow logic The logic for the 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. Warning Note that parameters such as claims or acr_values might be changed by the user in the URL when the login request is sent from the client to the Red Hat build of Keycloak via the user's browser. This situation can be mitigated if client uses PAR (Pushed authorization request), a request object, or other mechanisms that prevents the user from rewrite the parameters in the URL. Hence after the authentication, clients are encouraged to check the ID Token to double-check that acr in the token corresponds to the expected 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. Note During the first authentication of the user, the first configured subflow with the Conditional - Level Of Authentication is always executed (regardless of the requested level) as the user does not yet have any level. Therefore, we recommend that the first level subflow contains the minimal required authenticators for user authentication. In addition, ensure that the subflows with different values of Conditional - Level Of Authentication are ordered starting with the lowest as shown in the example above. For example, if you configure a subflow with level 2 and then add another subflow with level 1, the level 2 subflow will be always asked during the first authentication, which may not be the desired behavior. Note A conflict situation may arise when an admin specifies several flows, sets different LoA levels to each, and assigns the flows to different clients. However, the rule is always the same: if a user has a certain level, it needs only have that level to connect to a client. It's up to the admin to make sure that the LoA is coherent. Example scenario Max Age is configured as 300 seconds for level 1 condition. Login request is sent without requesting any acr. Level 1 will be used and the user needs to authenticate with username and password. The token will have acr=1 . Another login request is sent after 100 seconds. The user is automatically authenticated due to the SSO and the token will return acr=1 . Another login request is sent after another 201 seconds (301 seconds since authentication in point 2). The user is automatically authenticated due to the SSO, but the token will return acr=0 due the level 1 is considered expired. Another login request is sent, but now it will explicitly request ACR of level 1 in the claims parameter. User will be asked to re-authenticate with username/password and then acr=1 will be returned in the token. 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. 8.3.5. Registration or Reset credentials requested by client 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: When the client wants the user to be redirected directly to the registration, the OIDC client should replace the very last snippet from the OIDC login URL path ( /auth ) with /registrations . So the full URL might be similar to the following: https://keycloak.example.com/realms/your_realm/protocol/openid-connect/registrations . When the client wants a user to be redirected directly to the Reset credentials flow, the OIDC client should replace the very last snippet from the OIDC login URL path ( /auth ) with /forgot-credentials . Warning The preceding steps are the only supported method for a client to directly request a registration or reset-credentials flow. For security purposes, it is not supported and recommended for client applications to bypass OIDC/SAML flows and directly redirect to other Red Hat build of Keycloak endpoints (such as for instance endpoints under /realms/realm_name/login-actions or /realms/realm_name/broker ). 8.4. User session limits Limits on the number of session that a user can have can be configured. Sessions can be limited per realm or per client. To add session limits to a flow, perform the following steps. Click Add step for the flow. Select User session count limiter from the item list. Click Add . Click Required for the User Session Count Limiter authentication type to set its requirement to required. Click ⚙\ufe0f (gear icon) for the User Session Count Limiter . Enter an alias for this config. Enter the required maximum number of sessions that a user can have in this realm. For example, if 2 is the value, 2 SSO sessions is the maximum that each user can have in this realm. If 0 is the value, this check is disabled. Enter the required maximum number of sessions a user can have for the client. For example, if 2 is the value, then 2 SSO sessions is the maximum in this realm for each client. So when a user is trying to authenticate to client foo , but that user has already authenticated in 2 SSO sessions to client foo , either the authentication will be denied or an existing sessions will be killed based on the behavior configured. If a value of 0 is used, this check is disabled. If both session limits and client session limits are enabled, it makes sense to have client session limits to be always lower than session limits. The limit per client can never exceed the limit of all SSO sessions of this user. Select the behavior that is required when the user tries to create a session after the limit is reached. Available behaviors are: Deny new session - when a new session is requested and the session limit is reached, no new sessions can be created. Terminate oldest session - when a new session is requested and the session limit has been reached, the oldest session will be removed and the new session created. Optionally, add a custom error message to be displayed when the limit is reached. Note that the user session limits should be added to your bound Browser flow , Direct grant flow , Reset credentials and also to any Post broker login flow . The authenticator should be added at the point when the user is already known during authentication (usually at the end of the authentication flow) and should be typically REQUIRED. Note that it is not possible to have ALTERNATIVE and REQUIRED executions at the same level. For most of authenticators like Direct grant flow , Reset credentials or Post broker login flow , it is recommended to add the authenticator as REQUIRED at the end of the authentication flow. Here is an example for the Reset credentials flow: For Browser flow, consider not adding the Session Limits authenticator at the top level flow. This recommendation is due to the Cookie authenticator, which automatically re-authenticates users based on SSO cookie. It is at the top level and it is better to not check session limits during SSO re-authentication because a user session already exists. So instead, consider adding a separate ALTERNATIVE subflow, such as the following authenticate-user-with-session-limit example at the same level like Cookie . Then you can add a REQUIRED subflow, in the following real-authentication-subflow`example, as a nested subflow of `authenticate-user-with-session-limit and add a User Session Limit at the same level as well. Inside the real-authentication-subflow , you can add real authenticators in a similar fashion to the default browser flow. The following example flow allows to users to authenticate with an identity provider or with password and OTP: Regarding Post Broker login flow , you can add the User Session Limits as the only authenticator in the authentication flow as long as you have no other authenticators that you trigger after authentication with your identity provider. However, make sure that this flow is configured as Post Broker Flow at your identity providers. This requirement exists needed so that the authentication with Identity providers also participates in the session limits. Note Currently, the administrator is responsible for maintaining consistency between the different configurations. So make sure that all your flows use same the configuration of User Session Limits . Note User session limit feature is not available for CIBA. 8.5. Kerberos Red Hat build of Keycloak supports login with a Kerberos ticket through the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) protocol. SPNEGO authenticates transparently through the web browser after the user authenticates the session. For non-web cases, or when a ticket is not available during login, Red Hat build of Keycloak supports login with Kerberos username and password. A typical use case for web authentication is the following: The user logs into the desktop. The user accesses a web application secured by Red Hat build of Keycloak using a browser. The application redirects to Red Hat build of Keycloak login. Red Hat build of Keycloak renders the HTML login screen with status 401 and HTTP header WWW-Authenticate: Negotiate If the browser has a Kerberos ticket from desktop login, the browser transfers the desktop sign-on information to Red Hat build of Keycloak in header Authorization: Negotiate 'spnego-token' . Otherwise, it displays the standard login screen, and the user enters the login credentials. Red Hat build of Keycloak validates the token from the browser and authenticates the user. If using LDAPFederationProvider with Kerberos authentication support, Red Hat build of Keycloak provisions user data from LDAP. If using KerberosFederationProvider, Red Hat build of Keycloak lets the user update the profile and pre-fill login data. Red Hat build of Keycloak returns to the application. Red Hat build of Keycloak and the application communicate through OpenID Connect or SAML messages. Red Hat build of Keycloak acts as a broker to Kerberos/SPNEGO login. Therefore Red Hat build of Keycloak authenticating through Kerberos is hidden from the application. Warning The Negotiate www-authenticate scheme allows NTLM as a fallback to Kerberos and on some web browsers in Windows NTLM is supported by default. If a www-authenticate challenge comes from a server outside a browsers permitted list, users may encounter an NTLM dialog prompt. A user would need to click the cancel button on the dialog to continue as Red Hat build of Keycloak does not support this mechanism. This situation can happen if Intranet web browsers are not strictly configured or if Red Hat build of Keycloak serves users in both the Intranet and Internet. A custom authenticator can be used to restrict Negotiate challenges to a whitelist of hosts. Perform the following steps to set up Kerberos authentication: The setup and configuration of the Kerberos server (KDC). The setup and configuration of the Red Hat build of Keycloak server. The setup and configuration of the client machines. 8.5.1. Setup of Kerberos server 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: Add some user principals to your Kerberos database. You can also integrate your Kerberos with LDAP, so user accounts provision from the LDAP server. Add service principal for "HTTP" service. For example, if the Red Hat build of Keycloak server runs on www.mydomain.org , add the service principal HTTP/www.mydomain.org@<kerberos realm> . On MIT Kerberos, you run a "kadmin" session. On a machine with MIT Kerberos, you can use the command: Then, add HTTP principal and export its key to a keytab file with commands such as: Ensure the keytab file /tmp/http.keytab is accessible on the host where Red Hat build of Keycloak is running. 8.5.2. Setup and configuration of Red Hat build of Keycloak server Install a Kerberos client on your machine. Procedure Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the freeipa-client package, containing a Kerberos client and other utilities. Configure the Kerberos client (on Linux, the configuration settings are in the /etc/krb5.conf file ). Add your Kerberos realm to the configuration and configure the HTTP domains your server runs on. For example, for the MYDOMAIN.ORG realm, you can configure the domain_realm section like this: Export the keytab file with the HTTP principal and ensure the file is accessible to the process running the Red Hat build of Keycloak server. For production, ensure that the file is readable by this process only. For the MIT Kerberos example above, we exported keytab to the /tmp/http.keytab file. If your Key Distribution Centre (KDC) and Red Hat build of Keycloak run on the same host, the file is already available. 8.5.2.1. Enabling SPNEGO processing By default, Red Hat build of Keycloak disables SPNEGO protocol support. To enable it, go to the browser flow and enable Kerberos . Browser flow Set the Kerberos requirement from disabled to alternative (Kerberos is optional) or required (browser must have Kerberos enabled). If you have not configured the browser to work with SPNEGO or Kerberos, Red Hat build of Keycloak falls back to the regular login screen. 8.5.2.2. Configure Kerberos user storage federation providers You must now use User Storage Federation to configure how Red Hat build of Keycloak interprets Kerberos tickets. Two different federation providers exist with Kerberos authentication support. To authenticate with Kerberos backed by an LDAP server, configure the LDAP Federation Provider . Procedure Go to the configuration page for your LDAP provider. Ldap kerberos integration Toggle Allow Kerberos authentication to ON Allow Kerberos authentication makes Red Hat build of Keycloak use the Kerberos principal access user information so information can import into the Red Hat build of Keycloak environment. If an LDAP server is not backing up your Kerberos solution, use the Kerberos User Storage Federation Provider. Procedure Click User Federation in the menu. Select Kerberos from the Add provider select box. Kerberos user storage provider The Kerberos provider parses the Kerberos ticket for simple principal information and imports the information into the local Red Hat build of Keycloak database. User profile information, such as first name, last name, and email, are not provisioned. 8.5.3. Setup and configuration of client machines 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. 8.5.4. Credential delegation 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); Note Configure forwardable Kerberos tickets in krb5.conf file and add support for delegated credentials to your browser. Warning Credential delegation has security implications, so use it only if necessary and only with HTTPS. See this article for more details and an example. 8.5.5. Cross-realm trust 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. Kerberos cross-realm trust The Red Hat build of Keycloak server supports cross-realm trust. To implement this, perform the following: Configure the Kerberos servers for the cross-realm trust. Implementing this step depends on the Kerberos server implementations. This step is necessary to add the Kerberos principal krbtgt/B@A to the Kerberos databases of realm A and B. This principal must have the same keys on both Kerberos realms. The principals must have the same password, key version numbers, and ciphers in both realms. Consult the Kerberos server documentation for more details. Note The cross-realm trust is unidirectional by default. You must add the principal krbtgt/A@B to both Kerberos databases for bidirectional trust between realm A and realm B. However, trust is transitive by default. If realm B trusts realm A and realm C trusts realm B, then realm C trusts realm A without the principal, krbtgt/C@A , available. Additional configuration (for example, capaths ) may be necessary on the Kerberos client-side so clients can find the trust path. Consult the Kerberos documentation for more details. Configure Red Hat build of Keycloak server When using an LDAP storage provider with Kerberos support, configure the server principal for realm B, as in this example: HTTP/mydomain.com@B . The LDAP server must find the users from realm A if users from realm A are to successfully authenticate to Red Hat build of Keycloak, because Red Hat build of Keycloak must perform the SPNEGO flow and then find the users. 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. When using a Kerberos user storage provider (typically, Kerberos without LDAP integration), configure the server principal as HTTP/mydomain.com@B , and users from Kerberos realms A and B must be able to authenticate. 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 . 8.5.6. Troubleshooting If you have issues, enable additional logging to debug the problem: Enable Debug flag in the Admin Console for Kerberos or LDAP federation providers Enable TRACE logging for category org.keycloak to receive more information in server logs Add system properties -Dsun.security.krb5.debug=true and -Dsun.security.spnego.debug=true 8.6. X.509 client certificate user authentication Red Hat build of Keycloak supports logging in with an X.509 client certificate if you have configured the server to use mutual SSL authentication. A typical workflow: A client sends an authentication request over SSL/TLS channel. During the SSL/TLS handshake, the server and the client exchange their x.509/v3 certificates. The container (JBoss EAP) validates the certificate PKIX path and the certificate expiration date. The x.509 client certificate authenticator validates the client certificate by using the following methods: Checks the certificate revocation status by using CRL or CRL Distribution Points. Checks the Certificate revocation status by using OCSP (Online Certificate Status Protocol). Validates whether the key in the certificate matches the expected key. Validates whether the extended key in the certificate matches the expected extended key. If any of the these checks fail, the x.509 authentication fails. Otherwise, the authenticator extracts the certificate identity and maps it to an existing user. When the certificate maps to an existing user, the behavior diverges depending on the authentication flow: In the Browser Flow, the server prompts users to confirm their identity or sign in with a username and password. In the Direct Grant Flow, the server signs in the user. Important Note that it is the responsibility of the web container to validate certificate PKIX path. X.509 authenticator on the Red Hat build of Keycloak side provides just the additional support for check the certificate expiration, certificate revocation status and key usage. If you are using Red Hat build of Keycloak deployed behind reverse proxy, make sure that your reverse proxy is configured to validate PKIX path. If you do not use reverse proxy and users directly access the JBoss EAP, you should be fine as JBoss EAP makes sure that PKIX path is validated as long as it is configured as described below. 8.6.1. Features Supported Certificate Identity Sources: Match SubjectDN by using regular expressions X500 Subject's email attribute X500 Subject's email from Subject Alternative Name Extension (RFC822Name General Name) X500 Subject's other name from Subject Alternative Name Extension. This other name is the User Principal Name (UPN), typically. X500 Subject's Common Name attribute Match IssuerDN by using regular expressions Certificate Serial Number Certificate Serial Number and IssuerDN SHA-256 Certificate thumbprint Full certificate in PEM format 8.6.1.1. Regular expressions Red Hat build of Keycloak extracts the certificate identity from Subject DN or Issuer DN by using a regular expression as a filter. For example, this regular expression matches the email attribute: The regular expression filtering applies if the Identity Source is set to either Match SubjectDN using regular expression or Match IssuerDN using regular expression . 8.6.1.1.1. Mapping certificate identity to an existing user The certificate identity mapping can map the extracted user identity to an existing user's username, email, or a custom attribute whose value matches the certificate identity. For example, setting Identity source to Subject's email or User mapping method to Username or email makes the X.509 client certificate authenticator use the email attribute in the certificate's Subject DN as the search criteria when searching for an existing user by username or by email. Important If you disable Login with email at realm settings, the same rules apply to certificate authentication. Users are unable to log in by using the email attribute. Using Certificate Serial Number and IssuerDN as an identity source requires two custom attributes for the serial number and the IssuerDN. SHA-256 Certificate thumbprint is the lowercase hexadecimal representation of SHA-256 certificate thumbprint. Using Full certificate in PEM format as an identity source is limited to the custom attributes mapped to external federation sources, such as LDAP. Red Hat build of Keycloak cannot store certificates in its database due to length limitations, so in the case of LDAP, you must enable Always Read Value From LDAP . 8.6.1.1.2. Extended certificate validation Revocation status checking using CRL. Revocation status checking using CRL/Distribution Point. Revocation status checking using OCSP/Responder URI. Certificate KeyUsage validation. Certificate ExtendedKeyUsage validation. 8.6.2. Adding X.509 client certificate authentication to browser flows Click Authentication in the menu. Click the Browser flow. From the Action list, select Duplicate . Enter a name for the copy. Click Duplicate . Click Add step . Click "X509/Validate Username Form". Click Add . X509 execution Click and drag the "X509/Validate Username Form" over the "Browser Forms" execution. Set the requirement to "ALTERNATIVE". X509 browser flow Click the Action menu. Click the Bind flow . Click the Browser flow from the drop-down list. Click Save . X509 browser flow bindings 8.6.3. Configuring X.509 client certificate authentication X509 configuration User Identity Source Defines the method for extracting the user identity from a client certificate. Canonical DN representation enabled Defines whether to use canonical format to determine a distinguished name. The official Java API documentation describes the format. This option affects the two User Identity Sources Match SubjectDN using regular expression and Match IssuerDN using regular expression only. Enable this option when you set up a new Red Hat build of Keycloak instance. Disable this option to retain backward compatibility with existing Red Hat build of Keycloak instances. Enable Serial Number hexadecimal representation Represent the serial number as hexadecimal. The serial number with the sign bit set to 1 must be left padded with 00 octet. For example, a serial number with decimal value 161 , or a1 in hexadecimal representation is encoded as 00a1 , according to RFC5280. See RFC5280, appendix-B for more details. A regular expression A regular expression to use as a filter for extracting the certificate identity. The expression must contain a single group. User Mapping Method Defines the method to match the certificate identity with an existing user. Username or email searches for existing users by username or email. Custom Attribute Mapper searches for existing users with a custom attribute that matches the certificate identity. The name of the custom attribute is configurable. A name of user attribute A custom attribute whose value matches against the certificate identity. Use multiple custom attributes when attribute mapping is related to multiple values, For example, 'Certificate Serial Number and IssuerDN'. CRL Checking Enabled Check the revocation status of the certificate by using the Certificate Revocation List. The location of the list is defined in the CRL file path attribute. Enable CRL Distribution Point to check certificate revocation status Use CDP to check the certificate revocation status. Most PKI authorities include CDP in their certificates. CRL file path The path to a file containing a CRL list. The value must be a path to a valid file if the CRL Checking Enabled option is enabled. CRL abort if non updated A CRL conforming to RFC5280 contains a update field that indicates the date by which the CRL will be issued. When that time is passed, the CRL is considered outdated and it should be refreshed. If this option is true , the authentication will fail if the CRL is outdated (recommended). If the option is set to false , the outdated CRL is still used to validate the user certificates. OCSP Checking Enabled Checks the certificate revocation status by using Online Certificate Status Protocol. OCSP Fail-Open Behavior By default the OCSP check must return a positive response in order to continue with a successful authentication. Sometimes however this check can be inconclusive: for example, the OCSP server could be unreachable, overloaded, or the client certificate may not contain an OCSP responder URI. When this setting is turned ON, authentication will be denied only if an explicit negative response is received by the OCSP responder and the certificate is definitely revoked. If a valid OCSP response is not available the authentication attempt will be accepted. OCSP Responder URI Override the value of the OCSP responder URI in the certificate. Validate Key Usage Verifies the certificate's KeyUsage extension bits are set. For example, "digitalSignature,KeyEncipherment" verifies if bits 0 and 2 in the KeyUsage extension are set. Leave this parameter empty to disable the Key Usage validation. See RFC5280, Section-4.2.1.3 for more information. Red Hat build of Keycloak raises an error when a key usage mismatch occurs. Validate Extended Key Usage Verifies one or more purposes defined in the Extended Key Usage extension. See RFC5280, Section-4.2.1.12 for more information. Leave this parameter empty to disable the Extended Key Usage validation. Red Hat build of Keycloak raises an error when flagged as critical by the issuing CA and a key usage extension mismatch occurs. Validate Certificate Policy Verifies one or more policy OIDs as defined in the Certificate Policy extension. See RFC5280, Section-4.2.1.4 . Leave the parameter empty to disable the Certificate Policy validation. Multiple policies should be separated using a comma. Certificate Policy Validation Mode When more than one policy is specified in the Validate Certificate Policy setting, it decides whether the matching should check for all requested policies to be present, or one match is enough for a successful authentication. Default value is All , meaning that all requested policies should be present in the client certificate. Bypass identity confirmation If enabled, X.509 client certificate authentication does not prompt the user to confirm the certificate identity. Red Hat build of Keycloak signs in the user upon successful authentication. Revalidate client certificate If set, the client certificate trust chain will be always verified at the application level using the certificates present in the configured trust store. This can be useful if the underlying web server does not enforce client certificate chain validation, for example because it is behind a non-validating load balancer or reverse proxy, or when the number of allowed CAs is too large for the mutual SSL negotiation (most browsers cap the maximum SSL negotiation packet size at 32767 bytes, which corresponds to about 200 advertised CAs). By default this option is off. 8.6.4. Adding X.509 Client Certificate Authentication to a Direct Grant Flow Click Authentication in the menu. Select Duplicate from the "Action list" to make a copy of the built-in "Direct grant" flow. Enter a name for the copy. Click Duplicate . Click the created flow. Click the trash can icon 🗑\ufe0f of the "Username Validation" and click Delete . Click the trash can icon 🗑\ufe0f of the "Password" and click Delete . Click Add step . Click "X509/Validate Username". Click Add . X509 direct grant execution Set up the x509 authentication configuration by following the steps described in the x509 Browser Flow section. Click the Bindings tab. Click the Direct Grant Flow drop-down list. Click the newly created "x509 Direct Grant" flow. Click Save . X509 direct grant flow bindings 8.6.4.1. Example using CURL The following example shows how to obtain an access token for a user in the realm test with the direct grant flow. The example is using OAuth2 Resource Owner Password Credentials Grant in the securing apps section and the confidential client resource-owner : curl \ -d "client_id=resource-owner" \ -d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \ -d "grant_type=password" \ --cacert /tmp/truststore.pem \ --cert /tmp/keystore.pem:kssecret \ "https://localhost:8543/realms/test/protocol/openid-connect/token" The file /tmp/truststore.pem points to the file with the truststore containing the certificate of the Red Hat build of Keycloak server. The file /tmp/keystore.pem contains the private key and certificates corresponding to the Red Hat build of Keycloak user, which would be successfully authenticated by this request. It is dependent on the configuration of the authenticator on how exactly is the content from the certificate mapped to the Red Hat build of Keycloak user as described in the configuration section . The kssecret might be the password of this keystore file. According to your environment, it might be needed to use more options to CURL commands like for instance: Option --insecure if you are using self-signed certificates Option --capath to include the whole directory containing the certificate authority path Options --cert-type or --key-type in case you want to use different files than PEM Please consult the documentation of the curl tool for the details if needed. If you are using other tools than curl , consult the documentation of your tool. However, the setup would be similar. A need exists to include keystore and truststore as well as client credentials in case you are using a confidential client. Note If it is possible, it is preferred to use Service accounts together with the MTLS client authentication (client authenticator X509 Certificate ) rather than using the Direct grant with X.509 authentication as direct grant may require sharing of the user certificate with client applications. When using service account, the tokens are obtained on behalf of the client itself, which in general is better and more secure practice. 8.7. W3C Web Authentication (WebAuthn) Red Hat build of Keycloak provides support for W3C Web Authentication (WebAuthn) . Red Hat build of Keycloak works as a WebAuthn's Relying Party (RP) . Note WebAuthn's operations success depends on the user's WebAuthn supporting authenticator, browser, and platform. Make sure your authenticator, browser, and platform support the WebAuthn specification. Note WebAuthn's specification uses a user.id to map a public key credential to a specific user account in the Relying Party. This user ID handle is an opaque byte sequence with a maximum size of 64 bytes. Red Hat build of Keycloak passes the internal database ID to the registration, which in common users is an UUID of 36 characters. But, if the user is from a external user federation provider, the internal Red Hat build of Keycloak ID is an storage ID in the form f:<provider-id>:<user-id> that can exceed the 64 byte limitation. Please take this into account and use short IDs for the federation provider component and for the users coming from that provider when combining the Storage SPI and WebAuthn. 8.7.1. Setup The setup procedure of WebAuthn support for 2FA is the following: 8.7.1.1. Enable WebAuthn authenticator registration Click Authentication in the menu. Click the Required Actions tab. Toggle the Webauthn Register switch to ON . Toggle the Default Action switch to ON if you want all new users to be required to register their WebAuthn credentials. 8.7.2. Adding WebAuthn authentication to a browser flow Click Authentication in the menu. Click the Browser flow. Select Duplicate from the "Action list" to make a copy of the built-in Browser flow. Enter "WebAuthn Browser" as the name of the copy. Click Duplicate . Click the name to go to the details Click the trash can icon 🗑\ufe0f of the "WebAuthn Browser Browser - Conditional OTP" and click Delete . If you require WebAuthn for all users: Click + menu of the WebAuthn Browser Forms . Click Add step . Click WebAuthn Authenticator . Click Add . Select Required for the WebAuthn Authenticator authentication type to set its requirement to required. Click the Action menu at the top of the screen. Select Bind flow from the drop-down list. Select Browser from the drop-down list. Click Save . Note If a user does not have WebAuthn credentials, the user must register WebAuthn credentials. Users can log in with WebAuthn if they have a WebAuthn credential registered only. So instead of adding the WebAuthn Authenticator execution, you can: Procedure Click + menu of the WebAuthn Browser Forms row. Click Add sub-flow . Enter "Conditional 2FA" for the name field. Select Conditional for the Conditional 2FA to set its requirement to conditional. On the Conditional 2FA row, click the plus sign + and select Add condition . Click Add condition . Select Condition - User Configured . Click Add . Select Required for the Condition - User Configured to set its requirement to required. Drag and drop WebAuthn Authenticator into the Conditional 2FA flow Select Alternative for the WebAuthn Authenticator to set its requirement to alternative. The user can choose between using WebAuthn and OTP for the second factor: Procedure On the Conditional 2FA row, click the plus sign + and select Add step . Select OTP Form from the list. Click Add . Select Alternative for the OTP Form to set its requirement to alternative. 8.7.3. Authenticate with WebAuthn authenticator After registering a WebAuthn authenticator, the user carries out the following operations: Open the login form. The user must authenticate with a username and password. The user's browser asks the user to authenticate by using their WebAuthn authenticator. 8.7.4. Managing WebAuthn as an administrator 8.7.4.1. Managing credentials Red Hat build of Keycloak manages WebAuthn credentials similarly to other credentials from User credential management : Red Hat build of Keycloak assigns users a required action to create a WebAuthn credential from the Reset Actions list and select Webauthn Register . Administrators can delete a WebAuthn credential by clicking Delete . Administrators can view the credential's data, such as the AAGUID, by selecting Show data... . Administrators can set a label for the credential by setting a value in the User Label field and saving the data. 8.7.4.2. Managing policy Administrators can configure WebAuthn related operations as WebAuthn Policy per realm. Procedure Click Authentication in the menu. Click the Policy tab. Click the WebAuthn Policy tab. Configure the items within the policy (see description below). Click Save . The configurable items and their description are as follows: Configuration Description Relying Party Entity Name The readable server name as a WebAuthn Relying Party. This item is mandatory and applies to the registration of the WebAuthn authenticator. The default setting is "keycloak". For more details, see WebAuthn Specification . Signature Algorithms The algorithms telling the WebAuthn authenticator which signature algorithms to use for the Public Key Credential . Red Hat build of Keycloak uses the Public Key Credential to sign and verify Authentication Assertions . If no algorithms exist, the default ES256 and RS256 is adapted. ES256 and RS256 are an optional configuration item applying to the registration of WebAuthn authenticators. For more details, see WebAuthn Specification . Relying Party ID The ID of a WebAuthn Relying Party that determines the scope of Public Key Credentials . The ID must be the origin's effective domain. This ID is an optional configuration item applied to the registration of WebAuthn authenticators. If this entry is blank, Red Hat build of Keycloak adapts the host part of Red Hat build of Keycloak's base URL. For more details, see WebAuthn Specification . Attestation Conveyance Preference The WebAuthn API implementation on the browser ( WebAuthn Client ) is the preferential method to generate Attestation statements. This preference is an optional configuration item applying to the registration of the WebAuthn authenticator. If no option exists, its behavior is the same as selecting "none". For more details, see WebAuthn Specification . Authenticator Attachment The acceptable attachment pattern of a WebAuthn authenticator for the WebAuthn Client. This pattern is an optional configuration item applying to the registration of the WebAuthn authenticator. For more details, see WebAuthn Specification . Require Discoverable Credential The option requiring that the WebAuthn authenticator generates the Public Key Credential as Client-side discoverable Credential . This option applies to the registration of the WebAuthn authenticator. If left blank, its behavior is the same as selecting "No". For more details, see WebAuthn Specification . User Verification Requirement The option requiring that the WebAuthn authenticator confirms the verification of a user. This is an optional configuration item applying to the registration of a WebAuthn authenticator and the authentication of a user by a WebAuthn authenticator. If no option exists, its behavior is the same as selecting "preferred". For more details, see WebAuthn Specification for registering a WebAuthn authenticator and WebAuthn Specification for authenticating the user by a WebAuthn authenticator . Timeout The timeout value, in seconds, for registering a WebAuthn authenticator and authenticating the user by using a WebAuthn authenticator. If set to zero, its behavior depends on the WebAuthn authenticator's implementation. The default value is 0. For more details, see WebAuthn Specification for registering a WebAuthn authenticator and WebAuthn Specification for authenticating the user by a WebAuthn authenticator . Avoid Same Authenticator Registration If enabled, Red Hat build of Keycloak cannot re-register an already registered WebAuthn authenticator. Acceptable AAGUIDs The white list of AAGUIDs which a WebAuthn authenticator must register against. 8.7.5. Attestation statement verification 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". 8.7.6. Managing WebAuthn credentials as a user 8.7.6.1. Register WebAuthn authenticator The appropriate method to register a WebAuthn authenticator depends on whether the user has already registered an account on Red Hat build of Keycloak. 8.7.6.2. New user If the WebAuthn Register required action is Default Action in a realm, new users must set up the Passkey after their first login. Procedure Open the login form. Click Register . Fill in the items on the form. Click Register . After successfully registering, the browser asks the user to enter the text of their WebAuthn authenticator's label. 8.7.6.3. Existing user If WebAuthn Authenticator is set up as required as shown in the first example, then when existing users try to log in, they are required to register their WebAuthn authenticator automatically: Procedure Open the login form. Enter the items on the form. Click Save . Click Login . After successful registration, the user's browser asks the user to enter the text of their WebAuthn authenticator's label. 8.7.7. Passwordless WebAuthn together with Two-Factor 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 . 8.7.7.1. Setup Set up WebAuthn passwordless support as follows: (if not already present) Register a new required action for WebAuthn passwordless support. Use the steps described in Enable WebAuthn Authenticator Registration . Register the Webauthn Register Passwordless action. Configure the policy. You can use the steps and configuration options described in Managing Policy . Perform the configuration in the Admin Console in the tab WebAuthn Passwordless Policy . Typically the requirements for the Passkey will be stronger than for the two-factor policy. For example, you can set the User Verification Requirement to Required when you configure the passwordless policy. Configure the authentication flow. Use the WebAuthn Browser flow described in Adding WebAuthn Authentication to a Browser Flow . Configure the flow as follows: The WebAuthn Browser Forms subflow contains Username Form as the first authenticator. Delete the default Username Password Form authenticator and add the Username Form authenticator. This action requires the user to provide a username as the first step. There will be a required subflow, which can be named Passwordless Or Two-factor , for example. This subflow indicates the user can authenticate with Passwordless WebAuthn credential or with Two-factor authentication. The flow contains WebAuthn Passwordless Authenticator as the first alternative. The second alternative will be a subflow named Password And Two-factor Webauthn , for example. This subflow contains a Password Form and a WebAuthn Authenticator . The final configuration of the flow looks similar to this: PasswordLess flow You can now add WebAuthn Register Passwordless as the required action to a user, already known to Red Hat build of Keycloak, to test this. During the first authentication, the user must use the password and second-factor WebAuthn credential. The user does not need to provide the password and second-factor WebAuthn credential if they use the WebAuthn Passwordless credential. 8.7.8. LoginLess WebAuthn 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 . 8.7.8.1. Setup Procedure Set up WebAuthn Loginless support as follows: (if not already present) Register a new required action for WebAuthn passwordless support. Use the steps described in Enable WebAuthn Authenticator Registration . Register the Webauthn Register Passwordless action. Configure the WebAuthn Passwordless Policy . Perform the configuration in the Admin Console, Authentication section, in the tab Policies WebAuthn Passwordless Policy . You have to set User Verification Requirement to required and Require Discoverable Credential to Yes when you configure the policy for loginless scenario. Note that since there isn't a dedicated Loginless policy it won't be possible to mix authentication scenarios with user verification=no/discoverable credential=no and loginless scenarios (user verification=yes/discoverable credential=yes). Storage capacity is usually very limited on Passkeys meaning that you won't be able to store many discoverable credentials on your Passkey. Configure the authentication flow. Create a new authentication flow, add the "WebAuthn Passwordless" execution and set the Requirement setting of the execution to Required The final configuration of the flow looks similar to this: LoginLess flow You can now add the required action WebAuthn Register Passwordless to a user, already known to Red Hat build of Keycloak, to test this. The user with the required action configured will have to authenticate (with a username/password for example) and will then be prompted to register a Passkey to be used for loginless authentication. 8.7.8.2. Vendor specific remarks 8.7.8.2.1. Compatibility check list Loginless authentication with Red Hat build of Keycloak requires the Passkey to meet the following features FIDO2 compliance: not to be confused with FIDO/U2F User verification: the ability for the Passkey to authenticate the user (prevents someone finding your Passkey to be able to authenticate loginless and passwordless) Discoverable Credential: the ability for the Passkey to store the login and the cryptographic keys associated with the client application 8.7.8.2.2. Windows Hello To use Windows Hello based credentials to authenticate against Red Hat build of Keycloak, configure the Signature Algorithms setting of the WebAuthn Passwordless Policy to include the RS256 value. Note that some browsers don't allow access to platform Passkey (like Windows Hello) inside private windows. 8.7.8.2.3. Supported Passkeys The following Passkeys have been successfully tested for loginless authentication with Red Hat build of Keycloak: Windows Hello (Windows 10 21H1/21H2) Yubico Yubikey 5 NFC Feitian ePass FIDO-NFC 8.8. Passkeys Red Hat build of Keycloak provides preview support for Passkeys . Red Hat build of Keycloak works as a Passkeys Relying Party (RP). Passkey registration and authentication are realized by the features of WebAuthn . Therefore, users of Red Hat build of Keycloak can do Passkey registration and authentication by existing WebAuthn registration and authentication . Note Both synced Passkeys and device-bound Passkeys can be used for both Same-Device and Cross-Device Authentication (CDA). However, Passkeys operations success depends on the user's environment. Make sure which operations can succeed in the environment . 8.8.1. Passkey Authentication with Conditional UI 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. Note This authentication uses the WebAuthn Conditional UI . Therefore, this authentication success depends on the user's environment. If the environment does not support WebAuthn Conditional UI, this authentication falls back to LoginLess WebAuthn . Note Passkey Authentication is Technology Preview and is not fully supported. This feature is disabled by default. To enable start the server with --features=preview or --features=passkeys 8.8.1.1. Setup Procedure Set up Passkey Authentication with Conditional UI as follows: (if not already present) Register a new required action for WebAuthn passwordless support. Use the steps described in Enable WebAuthn Authenticator Registration . Register the Webauthn Register Passwordless action. Configure the WebAuthn Passwordless Policy . Perform the configuration in the Admin Console, Authentication section, in the tab Policies WebAuthn Passwordless Policy . Set User Verification Requirement to required and Require discoverable credential to Yes when you configure the policy for loginless scenario. Note that since there is no dedicated Loginless policy, it is impossible to mix authentication scenarios with user verification=no/discoverable credential=no and loginless scenarios (user verification=yes/discoverable credential=yes). Note Storage capacity is usually very limited on hardware passkeys meaning that you cannot store many discoverable credentials on your passkey. However, this limitation may be mitigated for instance if you use an Android phone backed by a Google account as a passkey device or an iPhone backed by Bitwarden. Configure the authentication flow. Create a new authentication flow, add the Passkeys Conditional UI Authenticator execution and set the Requirement setting of the execution to Required . The final configuration of the flow looks similar to this: Bind the flow above as a browser authentication flow in the realm as described in the WebAuthn section above . The authentication flow above requires that user must already have passkey credential on his or her account to be able to log in. This requirement means that all users in the realm must have passkeys already set. That can be achieved for instance by enabling user registration as described below. 8.8.1.2. Setup of the registration for passkeys conditional UI Enable registration for your realm In the authentication flows of the realm, select flow registration and switch the authenticator Password validation to Disabled . This means that newly registered users will not be required to create the passwords in this example setup. Users must always use passkeys instead of passwords. Return to the Required actions sub-tab of the tab Authentication tab and find the Webauthn Register Passwordless action and mark it with Set as default action . This means that it would be added to all new users after their registration. The alternative to the registration flow setup is to add the required action WebAuthn Register Passwordless to a user who is already known to Red Hat build of Keycloak. The user with the required action configured will have to authenticate (with a username/password for example) and will then be prompted to register a passkey to be used for loginless authentication. Note We plan to improve the usability and allow integration of conditional passkeys with the existing authenticators and forms such as the default username / password form. Note From Web Authn Level 3 , Resident Key was replaced with Discoverable Credential . If a user's browser supports WebAuthn Conditional UI , the follwing screen is shown. Passkey Authentication with Conditional UI When the user clicks the Select your passkey textbox, a list of passkeys stored on a device where the user runs a browse is shown as follows. Passkey Authentication with Conditional UI Autofill If a user's browser does not support WebAuthn Conditional UI , the authenticaion falls back to the LoginLess WebAuthn as follows. Passkey Authentication with Conditional UI falling back to LoginLess WebAuthn 8.9. Recovery Codes (RecoveryCodes) You can configure Recovery codes for two-factor authentication by adding 'Recovery Authentication Code Form' as a two-factor authenticator to your authentication flow. For an example of configuring this authenticator, see WebAuthn . Note RecoveryCodes is Technology Preview and is not fully supported. This feature is disabled by default. To enable start the server with --features=preview or --features=recovery-codes 8.10. Conditions in conditional flows As was mentioned in Execution requirements , Condition executions can be only contained in Conditional subflow. If all Condition executions evaluate as true, then the Conditional sub-flow acts as Required . You can process the execution in the Conditional sub-flow. If some executions included in the Conditional sub-flow evaluate as false, then the whole sub-flow is considered as Disabled . 8.10.1. Available conditions Condition - User Role This execution has the ability to determine if the user has a role defined by User role field. If the user has the required role, the execution is considered as true and other executions are evaluated. The administrator has to define the following fields: Alias Describes a name of the execution, which will be shown in the authentication flow. User role Role the user should have to execute this flow. To specify an application role the syntax is appname.approle (for example myapp.myrole ). Condition - User Configured This checks if the other executions in the flow are configured for the user. The Execution requirements section includes an example of the OTP form. Condition - User Attribute This checks if the user has set up the required attribute: optionally, the check can also evaluate the group attributes. There is a possibility to negate output, which means the user should not have the attribute. The User Attributes section shows how to add a custom attribute. You can provide these fields: Alias Describes a name of the execution, which will be shown in the authentication flow. Attribute name Name of the attribute to check. Expected attribute value Expected value in the attribute. Include group attributes If On, the condition checks if any of the joined group has one attribute matching the configured name and value: this option can affect performance Negate output You can negate the output. In other words, the attribute should not be present. 8.10.2. Explicitly deny/allow access in conditional flows 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. Allow Access Authenticator will always successfully authenticate. This authenticator is not configurable. Deny Access Access will always be denied. You can define an error message, which will be shown to the user. You can provide these fields: Alias Describes a name of the execution, which will be shown in the authentication flow. Error message Error message which will be shown to the user. The error message could be provided as a particular message or as a property in order to use it with localization. (i.e. " You do not have the role 'admin'. ", my-property-deny in messages properties) Leave blank for the default message defined as property access-denied . 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. Browser flow Condition - user role configuration Configuration of the Deny Access is really easy. You can specify an arbitrary Alias and required message like this: The last thing is defining the property with an error message in the login theme messages_en.properties (for English): 8.11. Authentication sessions When a login page is opened for the first time in a web browser, Red Hat build of Keycloak creates an object called authentication session that stores some useful information about the request. Whenever a new login page is opened from a different tab in the same browser, Red Hat build of Keycloak creates a new record called authentication sub-session that is stored within the authentication session. Authentication requests can come from any type of clients such as the Admin CLI. In that case, a new authentication session is also created with one authentication sub-session. Please note that authentication sessions can be created also in other ways than using a browser flow. The authentication session usually expires after 30 minutes by default. The exact time is specified by the Login timeout switch in the Sessions tab of the admin console when configuring realms . 8.11.1. Authentication in more browser tabs As described in the 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.
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 claims= { "id_token": { "acr": { "essential": true, "values": ["gold"] } } } sudo kadmin.local addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG [domain_realm] .mydomain.org = MYDOMAIN.ORG mydomain.org = MYDOMAIN.ORG // 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); emailAddress=(.*?)(?:,|USD) curl -d "client_id=resource-owner" -d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" -d "grant_type=password" --cacert /tmp/truststore.pem --cert /tmp/keystore.pem:kssecret "https://localhost:8543/realms/test/protocol/openid-connect/token" deny-role1 = You do not have required role!