Chapter 8. Configuring authentication | Red Hat Product Documentation (2024)

Procedure

1. Click Authentication in the menu.
2. Click on the Browser item in the list to see the details.

Browser flow

Procedure

1. Click Authentication in the menu.
2. Click Create flow.

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

An empty new flow

• The structure of the flow and sub-flows.
• The executions within the flows
• The requirements set within the sub-flows and the executions.

Adding an authentication execution

Procedure

1. Click Authentication in the menu.
2. Click the Flows tab.
3. Click Create flow.
4. Enter Browser Password-less as a name.
5. Click Create.
6. Click Add execution.
7. Select Cookie from the list.
8. Click Add.
9. Select Alternative for the Cookie authentication type to set its requirement to alternative.
10. Click Add step.
11. Select Kerberos from the list.
12. Click Add.
13. Click Add step.
14. Select Identity Provider Redirector from the list.
15. Click Add.
16. Select Alternative for the Identity Provider Redirector authentication type to set its requirement to alternative.
17. Click Add sub-flow.
18. Enter Forms as a name.
19. Click Add.

20. Select Alternative for the Forms authentication type to set its requirement to alternative.

    The common part with the browser flow

    

21. Click + menu of the Forms execution.
22. Select Add step.
23. Select Username Form from the list.
24. Click Add.

1. Click + menu of the Forms sub-flow.
2. Click Add sub-flow.
3. Enter Authentication as name.
4. Click Add.
5. Select Required for the Authentication authentication type to set its requirement to required.
6. Click + menu of the Authentication sub-flow.
7. Click Add step.
8. Select WebAuthn Passwordless Authenticator from the list.
9. Click Add.
10. Select Alternative for the Webauthn Passwordless Authenticator authentication type to set its requirement to alternative.
11. Click + menu of the Authentication sub-flow.
12. Click Add sub-flow.
13. Enter Password with OTP as name.
14. Click Add.
15. Select Alternative for the Password with OTP authentication type to set its requirement to alternative.
16. Click + menu of the Password with OTP sub-flow.
17. Click Add step.
18. Select Password Form from the list.
19. Click Add.
20. Select Required for the Password Form authentication type to set its requirement to required.
21. Click + menu of the Password with OTP sub-flow.
22. Click Add step.
23. Select OTP Form from the list.
24. Click Add.
25. Click Required for the OTP Form authentication type to set its requirement to required.

1. Click the Action menu at the top of the screen.
2. Select Bind flow from the menu.
3. Click the Browser Flow drop-down list.
4. Click Save.

A password-less browser login

Procedure

1. Click Authentication in the menu.
2. Click the Flows tab.
3. Click Create flow.
4. Enter Browser Incl Step up Mechanism as a name.
5. Click Save.
6. Click Add execution.
7. Select Cookie from the list.
8. Click Add.
9. Select Alternative for the Cookie authentication type to set its requirement to alternative.
10. Click Add sub-flow.
11. Enter Auth Flow as a name.
12. Click Add.
13. Click Alternative for the Auth Flow authentication type to set its requirement to alternative.

1. Click + menu of the Auth Flow.
2. Click Add sub-flow.
3. Enter 1st Condition Flow as a name.
4. Click Add.
5. Click Conditional for the 1st Condition Flow authentication type to set its requirement to conditional.
6. Click + menu of the 1st Condition Flow.
7. Click Add condition.
8. Select Conditional - Level Of Authentication from the list.
9. Click Add.
10. Click Required for the Conditional - Level Of Authentication authentication type to set its requirement to required.
11. Click ⚙️ (gear icon).
12. Enter Level 1 as an alias.
13. Enter 1 for the Level of Authentication (LoA).
14. 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 re-use 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.

15. Click Save

    Configure the condition for the first authentication level

    

16. Click + menu of the 1st Condition Flow.
17. Click Add step.
18. Select Username Password Form from the list.
19. Click Add.

1. Click + menu of the Auth Flow.
2. Click Add sub-flow.
3. Enter 2nd Condition Flow as an alias.
4. Click Add.
5. Click Conditional for the 2nd Condition Flow authentication type to set its requirement to conditional.
6. Click + menu of the 2nd Condition Flow.
7. Click Add condition.
8. Select Conditional - Level Of Authentication from the item list.
9. Click Add.
10. Click Required for the Conditional - Level Of Authentication authentication type to set its requirement to required.
11. Click ⚙️ (gear icon).
12. Enter Level 2 as an alias.
13. Enter 2 for the Level of Authentication (LoA).
14. 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.

15. Click Save

    Configure the condition for the second authentication level

    

16. Click + menu of the 2nd Condition Flow.
17. Click Add step.
18. Select OTP Form from the list.
19. Click Add.
20. Click Required for the OTP Form authentication type to set its requirement to required.

1. Click the Action menu at the top of the screen.
2. Select Bind flow from the list.
3. Select Browser Flow in the dropdown.
4. 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:

1. Max Age is configured as 300 seconds for level 1 condition.
2. 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.
3. Another login request is sent after 100 seconds. The user is automatically authenticated due to the SSO and the token will return acr=1.
4. 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.
5. 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.

• 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 .

1. Add some user principals to your Kerberos database. You can also integrate your Kerberos with LDAP, so user accounts provision from the LDAP server.

2. 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:

Procedure

1. Install a Kerberos client. If your machine runs Fedora, Ubuntu, or RHEL, install the freeipa-client package, containing a Kerberos client and other utilities.

2. 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:

   [domain_realm] .mydomain.org = MYDOMAIN.ORG mydomain.org = MYDOMAIN.ORG

3. 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.

Kerberos cross-realm trust

• 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.

• 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.

• 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.

• 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

• 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

1. Click Authentication in the menu.
2. Click the Browser flow.
3. From the Action list, select Duplicate.
4. Enter a name for the copy.
5. Click Duplicate.
6. Click Add step.
7. Click "X509/Validate Username Form".

8. Click Add.

   X509 execution

   

9. Click and drag the "X509/Validate Username Form" over the "Browser Forms" execution.

10. Set the requirement to "ALTERNATIVE".

    X509 browser flow

    

11. Click the Action menu.
12. Click the Bind flow.
13. Click the Browser flow from the drop-down list.

14. Click Save.

    X509 browser flow bindings

    

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.

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.

1. Click Authentication in the menu.
2. Select Duplicate from the "Action list" to make a copy of the built-in "Direct grant" flow.
3. Enter a name for the copy.
4. Click Duplicate.
5. Click the created flow.
6. Click the trash can icon 🗑️ of the "Username Validation" and click Delete.
7. Click the trash can icon 🗑️ of the "Password" and click Delete.
8. Click Add step.
9. Click "X509/Validate Username".

10. Click Add.

    X509 direct grant execution

    

11. Set up the x509 authentication configuration by following the steps described in the x509 Browser Flow section.
12. Click the Bindings tab.
13. Click the Direct Grant Flow drop-down list.
14. Click the newly created "x509 Direct Grant" flow.

15. Click Save.

    X509 direct grant flow bindings

    

1. Click Authentication in the menu.
2. Click the Browser flow.
3. Select Duplicate from the "Action list" to make a copy of the built-in Browser flow.
4. Enter "WebAuthn Browser" as the name of the copy.
5. Click Duplicate.
6. Click the name to go to the details
7. Click the trash can icon 🗑️ of the "WebAuthn Browser Browser - Conditional OTP" and click Delete.

1. Click + menu of the WebAuthn Browser Forms.
2. Click Add step.
3. Click WebAuthn Authenticator.
4. Click Add.

5. Select Required for the WebAuthn Authenticator authentication type to set its requirement to required.

   

6. Click the Action menu at the top of the screen.
7. Select Bind flow from the drop-down list.
8. Select Browser from the drop-down list.
9. Click Save.

Procedure

1. Click + menu of the WebAuthn Browser Forms row.
2. Click Add sub-flow.
3. Enter "Conditional 2FA" for the name field.
4. Select Conditional for the Conditional 2FA to set its requirement to conditional.
5. On the Conditional 2FA row, click the plus sign + and select Add condition.
6. Click Add condition.
7. Select Condition - User Configured.
8. Click Add.
9. Select Required for the Condition - User Configured to set its requirement to required.
10. Drag and drop WebAuthn Authenticator into the Conditional 2FA flow

11. Select Alternative for the WebAuthn Authenticator to set its requirement to alternative.

    

Procedure

1. On the Conditional 2FA row, click the plus sign + and select Add step.
2. Select OTP Form from the list.
3. Click Add.

4. Select Alternative for the OTP Form to set its requirement to alternative.

   

• 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.

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.

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.

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: