Server Administration Guide

Every UI screen is internationalized in Red Hat Single Sign-On. The default language is English, but you can choose which locales you want to support and what the default locale will be.

The next time a user logs in, that user can choose a language on the login page to use for the login screens, Account Console, and Admin Console.

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

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

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

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

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

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

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

To change this behavior, perform these steps:

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

When you save this setting, a remember me checkbox displays on the realm’s login page.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Configure the global truststore for Red Hat Single Sign-On with the Truststore SPI. For more information about configuring the global truststore, see the Server Installation and Configuration Guide. If you do not configure the Truststore SPI, the truststore falls back to the default mechanism provided by Java, which can be the file supplied by the javax.net.ssl.trustStore system property or the cacerts file from the JDK if the system property is unset.

The Use Truststore SPI configuration property, in the LDAP federation provider configuration, controls the truststore SPI. By default, Red Hat Single Sign-On sets the property to Only for ldaps, which is adequate for most deployments. Red Hat Single Sign-On uses the Truststore SPI if the connection URL to LDAP starts with ldaps only.

If you set the Import Users option, the LDAP Provider handles importing LDAP users into the Red Hat Single Sign-On local database. The first time a user logs in, the LDAP provider imports the LDAP user into the Red Hat Single Sign-On database and validates the LDAP password. This first time a user logs in is the only time Red Hat Single Sign-On imports the user. If you click the Users menu in the Admin Console and click the View all users button, you only see the LDAP users authenticated at least once by Red Hat Single Sign-On. Red Hat Single Sign-On imports users this way, so this operation does not trigger an import of the entire LDAP user database.

If you want to sync all LDAP users into the Red Hat Single Sign-On database, configure and enable the Sync Settings on the LDAP provider configuration page.

Two types of synchronization exist:

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

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

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

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

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

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

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

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

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

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

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

For tracking the performance or connection pooling issues, consider setting the value of property Connection Pool Debug Level of the LDAP provider to value all. This will add lots of additional messages to server log with the included logging for the LDAP connection pooling. This can be used to track the issues related to connection pooling or performance.

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

For the case of reporting LDAP issue, you may consider to attach some part of your LDAP tree with the target data, which causes issues in your environment. For example if login of some user takes lot of time, you can consider attach his LDAP entry showing count of member attributes of various "group" entries. In this case, it might be useful to add if those group entries are mapped to some Group LDAP mapper (or Role LDAP Mapper) in Red Hat Single Sign-On and so on.

The FreeIPA Docker image is available in Docker Hub. To set up the FreeIPA server, see the FreeIPA documentation.

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

Red Hat Single Sign-On uses DBus-Java to communicate at a low level with D-Bus. D-Bus depends on the Unix Sockets Library.

Before enabling the SSSD Federation provider, install the RPM for this library:

$ sudo yum install rh-sso7-libunix-dbus-java

Red Hat Single Sign-On uses JNA to authenticate with PAM. Ensure you have the JAN package installed.

$ sudo yum install jna

Use the sssctl user-checks command to validate your setup:

  $ sudo sssctl user-checks admin -s keycloak

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

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

If OTP is conditional in your realm, the user must navigate to Red Hat Single Sign-On Account Console to reconfigure a new OTP generator. If OTP is required, then the user must reconfigure a new OTP generator when logging in.

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

Enable users to self-register.

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

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

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

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

You can enable a required action that new users must accept the terms and conditions before logging in to Red Hat Single Sign-On for the first time.

You enable this capability on the Required Actions tab.

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

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

In addition to enabling the declarative_user_profile feature, you should enable User Profile for a realm. To do that, click on the Realm Settings link on the left side menu and turn on the User Profile Enabled switch.

Once you enable it and click on the Save button, you can access the User Profile tab from where you can manage the configuration for user attributes.

By enabling the user profile for a realm, Red Hat Single Sign-On is going to impose additional constraints on how attributes are managed based on the user profile configuration. In summary, here is the list of what you should expect when the feature is enabled:

In the next topics, we’ll be exploring how to manage the user profile configuration and how it affects your realm.

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

In the Attributes sub-tab you have a list of the attributes currently associated with the user profile. By default, the configuration is created based on the user root attributes and each attribute is configured with some defaults in terms of validation and permissioning.

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

In the JSON Editor sub-tab you can view and edit the configuration using a well-defined JSON schema. Any change you make when at any other tab are reflected in the JSON configuration shown at this tab.

In the next section, you are going to learn how to manage the configuration from the Attributes sub-tab.

At the Attributes sub-tab you can create, edit, and delete the attributes associated with the user profile.

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

When configuring the attribute you can define the following settings:

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

To create a new group, click on the Create button in the top-right corner of the attribute groups listing.

When configuring the group you can define the following settings:

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

The JSON schema is defined as follows:

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": [ "user", "admin" ],
        "scopes": [ "foo", "bar" ]
      },
      "permissions": {
        "view": [ "admin", "user" ],
        "edit": [ "admin", "user" ]
      },
      "validations": {
        "email": {},
        "length": {
          "max": 255
        }
      },
      "annotations": {
        "myannotation": "myannotation-value"
      }
    }
  ],
  "groups": [
    {
      "name": "personalInfo",
      "displayHeader": "Personal Information"
    }
  ]
}

The schema supports as many attributes as you need.

For each attribute you should define a name and, optionally, the required, permission, and the annotations settings.

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

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

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

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

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

One of the main capabilities of User Profile is the possibility to dynamically render user-facing forms based on attributes metadata. When you have the feature enabled to your realm, forms like registration and update profile are rendered using specific theme templates to dynamically render pages based on the user profile configuration.

That said, you shouldn’t need to customize templates at all if the default rendering mechanisms serves to your needs. In case you still need customizations to themes, here are the templates you should be looking at:

The default rendering mechanism provides the following capabilities:

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

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

In order to make sure user profiles are in compliance with the configuration, administrators may use the VerifyProfile required action to eventually force users to update their profiles when authenticating to Red Hat Single Sign-On.

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

By default, the VerifyProfile action is disabled. To enabled it, click on the Authentication link on the left side menu and then click on the Required Actions tab. At this tab, click on the Register button and select the VerifyProfile action.

Before enabling the User Profile capabilities to a realm, there are some important considerations you should be aware of. By providing a single place to manage attribute metadata, the feature is very strict about the attributes that can be set to users and how they are managed.

In terms of user management, administrators are able to manage only the attributes defined in the user profile configuration. Any other attribute set to the user and not yet defined in the user profile configuration won’t be accessible. It is recommended to update your user profile configuration with all the user attributes you want to expose either to users or administrators.

The same recommendation applies for those accessing the User REST API to query user information.

In regards to Red Hat Single Sign-On internal user attributes such as LDAP_ID, LDAP_ENTRY_DN, or KERBEROS_PRINCIPAL, if you want to be able to access those attributes you should have them as attributes in your user profile configuration. The recommendation is to mark these attributes as viewable only to administrators so that you can look at them when managing the user attributes through the administration console or querying users via User API.

In regards to theming, if you already have customizations to the legacy templates (those hardcoded with user root attributes) your custom templates won’t be used when rendering user-facing forms but the new templates that render these forms dynamically. Ideally, you should avoid having any customizations to templates and try to stick with the behavior provided by these new templates to dynamically render forms for you. If they are still not enough to address your requirements, you can either customize them or provide us with any feedback so that we discuss whether it makes sense to enhance the new templates.

You can log out all users in the realm by clicking the Logout all button.

When you click the Logout all button, all SSO cookies become invalid, and clients requesting authentication within active browser sessions must log in again. Red Hat Single Sign-On notifies clients by using the Red Hat Single Sign-On OIDC client adapter of the logout event. Client types such as SAML do not receive a back-channel logout request.

On the Sessions page, you can click on each client to go to that client’s Sessions tab. Click the Show Sessions button there to see which users are in the application.

If you go to the Sessions tab of an individual user, you can also view the user’s session information.

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

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

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

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

This screenshot shows that some default groups already exist.

The algorithms available in Red Hat Single Sign-On 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 Single Sign-On uses a shared counter rather than the current time. The Red Hat Single Sign-On 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 re-use TOTPs in the valid time interval.

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

In the drop-down list, select browser to display the Browser Flow screen.

Hover over the question-mark tooltip of the drop-down list to view a description of the flow. Two sections exist.

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

To create a flow, perform the following:

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

When Red Hat Single Sign-On has created the flow, Red Hat Single Sign-On displays the Delete, Add execution, and Add flow buttons.

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

Executions have a wide variety of actions, from sending a reset email to validating an OTP. Add executions with the Add execution button. Hover over the question mark next to Provider, to see a description of the execution.

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 flow button. The Add 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 generic (default) or form. The form type constructs a sub-flow that generates a form for the user, similar to the built-in Registration flow. Sub-flows success depends on how their executions evaluate, including their contained sub-flows. See the execution requirements section for an in-depth explanation of how sub-flows work.

All elements in a flow have a Delete option in the Actions menu. This action removes the element from the flow. Executions have a Config menu option to configure the execution. It is also possible to add executions and sub-flows to sub-flows with the Add execution and Add flow menu options.

Since the order of execution is important, you can move executions and sub-flows up and down within their flows using the up and down buttons beside their names.

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

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

Finally, change the bindings.

After entering the username, the flow works as follows:

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

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

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

Now you configure the flow for the first authentication level.

Now you configure the flow for the second authentication level.

Finally, change the bindings.

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

The claims parameter is specified in a JSON representation:

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

The Red Hat Single Sign-On javascript adapter has support for easy construct of this JSON and sending it in the login request. See Javascript adapter documentation for more details.

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

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

For more details see the official OIDC specification.

Flow logic

The logic for the previous configured authentication flow is as follows:
If a client request a high authentication level, meaning Level of Authentication 2 (LoA 2), a user has to perform full 2-factor authentication: Username/Password + OTP. However, if a user already has a session in 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 settings helps to decide whether the user will be asked to present the authentication factor again during a subsequent authentication. If the particular level X is requested by the claims or acr_values parameter and user already authenticated with level X, but it is expired (for example max age is configured to 300 and user authenticated before 310 seconds) then the user will be asked to re-authenticate again with the particular level. However if the level is not yet expired, the user will be automatically considered as authenticated with that level.

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

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

Example scenario

ACR claim in the token

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

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

Note when the login request initiates a request with the claims parameter requesting acr as essential claim, then Red Hat Single Sign-On 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 Single Sign-On will throw an error.

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.

Note that the user session limits should be added to your bound Browser Flow, Direct Grant Flow, Reset Credentials and also to any Post Login Flow on any configured Identity Providers. Currently, the administrator is responsible for maintaining consistency between the different configurations.

Note also that the user session limit feature is not available for CIBA.

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

During setup, perform these steps:

sudo kadmin.local

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

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

Ensure the keytab file /tmp/http.keytab is accessible on the host where Red Hat Single Sign-On is running.

Install a Kerberos client on your machine.

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

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

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

Kerberos supports the credential delegation. Applications may need access to the Kerberos ticket so they can re-use it to interact with other services secured by Kerberos. Because the Red Hat Single Sign-On 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 Single Sign-On transmits this to your application from the Red Hat Single Sign-On 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 Single Sign-On before using it to make GSS calls against other services. When you deserialize the credential from the access token to the GSSCredential object, create the GSSContext with this credential passed to the GSSManager.createContext method. For example:

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

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

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

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

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

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

The Red Hat Single Sign-On server supports cross-realm trust. To implement this, perform the following:

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

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

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

Supported Certificate Identity Sources:

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

The following sections describe how to configure JBoss EAP/Undertow and the Red Hat Single Sign-On Server to enable X.509 client certificate authentication.

<security-realms>
    <security-realm name="ssl-realm">
        <server-identities>
            <ssl>
                <keystore path="servercert.jks"
                          relative-to="jboss.server.config.dir"
                          keystore-password="servercert password"/>
            </ssl>
        </server-identities>
        <authentication>
            <truststore path="truststore.jks"
                        relative-to="jboss.server.config.dir"
                        keystore-password="truststore password"/>
        </authentication>
    </security-realm>
</security-realms>

<subsystem xmlns="urn:jboss:domain:undertow:12.0">
	....
    <server name="default-server">
	    <https-listener name="default"
                        socket-binding="https"
                        security-realm="ssl-realm"
                        verify-client="REQUESTED"/>
    </server>
</subsystem>

When the Red Hat Single Sign-On server receives a direct HTTP request, the JBoss EAP undertow subsystem establishes an SSL handshake and extracts the client certificate. The JBoss EAP saves the client certificate to the javax.servlet.request.X509Certificate attribute of the HTTP request, as specified in the servlet specification. The Red Hat Single Sign-On X509 authenticator can look up the certificate from this attribute.

However, when the Red Hat Single Sign-On server listens to HTTP requests behind a load balancer or reverse proxy, the proxy server may extract the client certificate and establish a mutual SSL connection. A reverse proxy generally puts the authenticated client certificate in the HTTP header of the underlying request. The proxy forwards the request to the back end Red Hat Single Sign-On server. In this case, Red Hat Single Sign-On must look up the X.509 certificate chain from the HTTP headers rather than the attribute of the HTTP request.

If Red Hat Single Sign-On is behind a reverse proxy, you generally need to configure the alternative provider of the x509cert-lookup SPI in RHSSO_HOME/standalone/configuration/standalone.xml. With the default provider looking up the HTTP header certificate, two additional built-in providers exist: haproxy and apache.

<spi name="x509cert-lookup">
    <default-provider>haproxy</default-provider>
    <provider name="haproxy" enabled="true">
        <properties>
            <property name="sslClientCert" value="SSL_CLIENT_CERT"/>
            <property name="sslCertChainPrefix" value="CERT_CHAIN"/>
            <property name="certificateChainLength" value="10"/>
        </properties>
    </provider>
</spi>

<spi name="x509cert-lookup">
    <default-provider>apache</default-provider>
    <provider name="apache" enabled="true">
        <properties>
            <property name="sslClientCert" value="SSL_CLIENT_CERT"/>
            <property name="sslCertChainPrefix" value="CERT_CHAIN"/>
            <property name="certificateChainLength" value="10"/>
        </properties>
    </provider>
</spi>

<spi name="x509cert-lookup">
    <default-provider>nginx</default-provider>
    <provider name="nginx" enabled="true">
        <properties>
            <property name="sslClientCert" value="ssl-client-cert"/>
            <property name="sslCertChainPrefix" value="USELESS"/>
            <property name="certificateChainLength" value="2"/>
        </properties>
    </provider>
</spi>

 ...
 server {
    ...
    ssl_client_certificate                  trusted-ca-list-for-client-auth.pem;
    ssl_verify_client                       optional_no_ca;
    ssl_verify_depth                        2;
    ...
    location / {
      ...
      proxy_set_header ssl-client-cert        $ssl_client_escaped_cert;
      ...
    }
    ...
}

...
    <profile>
        <subsystem xmlns="urn:jboss:domain:logging:8.0">
...
            <logger category="org.keycloak.authentication.authenticators.x509">
                <level name="TRACE"/>
            </logger>
            <logger category="org.keycloak.services.x509">
                <level name="TRACE"/>
            </logger>

You can use the following template to request a token by using the Resource Owner Password Credentials Grant:

$ LOC=<install-dir>/intermediate1/user-certificate

$ curl --insecure https://localhost:8443/auth/realms/X509_demo/protocol/openid-connect/token --data "grant_type=password" -E $LOC/user1.crt --key $LOC/user1.key --cacert $LOC/intermediate-ca-chain.crt -d client_id=account -d client_secret=BNm5AQPJGEtbayIAoiKUetr0lkXKSlF4 | jq
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 2097 100 2013 100 84 25481 1063 -::- -::- -::- 26544
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ1OUNpN0tzUjBIOEFCQXEtQ1Z4SEFDSUo1M1hNYWVhclJrYkw4cFd1VW4wIn0.eyJleHAiOjE2Njc4MzA5NjAsImlhdCI6MTY2NzgzMDY2MCwianRpIjoiNDU5YzE2OGMtODU3ZS00OWRjLTgxYjItZjVhM2M3M2MwODMzIiwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODQ0My9hdXRoL3JlYWxtcy9YNTA5X2RlbW8iLCJzdWIiOiIwODZiMTgyZC00MzdhLTQzZDItYTRmZS05ZGZmYTNmOTBiZDAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJhY2NvdW50Iiwic2Vzc2lvbl9zdGF0ZSI6ImMwYjNiMTJjLTM5YmEtNGQ0Ni1iNDNlLTZkMTM0MGJmNTA5OCIsImFjciI6IjEiLCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJwcm9maWxlIGVtYWlsIiwic2lkIjoiYzBiM2IxMmMtMzliYS00ZDQ2LWI0M2UtNmQxMzQwYmY1MDk4IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyMSIsImVtYWlsIjoidXNlckByZWRoYXQuY29tIn0.CDtltEkmITloDpqU5alq4U1JopqEJVeoglT-wA43edQ_DfeWSgefL0BIrPlt1SKhFMOVitwyq_9XZvfiS5ZiObE33cDmhr6eohbUtDPibU2GuEIYP9WjlVpZDMaSKQVu5SwM91m6yei22PtH-ApPOBeG4Ru0xZtNXjwGQpuIJEi_H1rZdPY3I4U2lPuQo4Uono5gnF7re_nUvf90FJi0uaOOrsvUhUkj1xEwQ0Diy1oIymcbrDL0Ek7B30StBcjn-fe3-0GpLttLQju0OGTkwD7Eb0UWTKoWAwspMlgpf9NaIGj8rmBsz6eBlGIGWBN2Qg6v3PzbJ2NXKvq435f9Zg",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyMmFkZDdhMy0xN2RjLTQ5NmQtYTk4NS05YWZhNGZhODVhMTEifQ.eyJleHAiOjE2Njc4MzI0NjAsImlhdCI6MTY2NzgzMDY2MCwianRpIjoiZWU4MjJhMzYtMWEzMS00ZGEzLWIxMGEtNmY1ODkxYmI0MzlhIiwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODQ0My9hdXRoL3JlYWxtcy9YNTA5X2RlbW8iLCJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo4NDQzL2F1dGgvcmVhbG1zL1g1MDlfZGVtbyIsInN1YiI6IjA4NmIxODJkLTQzN2EtNDNkMi1hNGZlLTlkZmZhM2Y5MGJkMCIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJhY2NvdW50Iiwic2Vzc2lvbl9zdGF0ZSI6ImMwYjNiMTJjLTM5YmEtNGQ0Ni1iNDNlLTZkMTM0MGJmNTA5OCIsInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsInNpZCI6ImMwYjNiMTJjLTM5YmEtNGQ0Ni1iNDNlLTZkMTM0MGJmNTA5OCJ9.MubgR9rvyrmSOcaq5ce-qVTPenVQye1KsEHJr7nh9-A",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "c0b3b12c-39ba-4d46-b43e-6d1340bf5098",
"scope": "profile email"
}

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

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

When registering a WebAuthn authenticator, Red Hat Single Sign-On verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. Red Hat Single Sign-On requires the trust anchor’s certificates for this. Red Hat Single Sign-On uses the Keycloak truststore, so you must import these certificates into it in advance.

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

Red Hat Single Sign-On 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 Single Sign-On without a password. Red Hat Single Sign-On 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 Security Keys registered by users for the WebAuthn passwordless authentication meet different requirements. For example, the security keys may require users to authenticate to the security key using a PIN, or the security key attests with a stronger certificate authority.

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

Red Hat Single Sign-On 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 Single Sign-On without submitting a login or a password. Red Hat Single Sign-On can use WebAuthn as both the loginless/passwordless and two-factor authentication mechanism in the context of a realm.

An administrator typically requires that Security Keys registered by users for the WebAuthn loginless authentication meet different requirements. Loginless authentication requires users to authenticate to the security key (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 security key. Not all security keys meet that kind of requirements. Check with your security key vendor if your device supports 'user verification' and 'resident key'. See Supported Security Keys.

Red Hat Single Sign-On 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.

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

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

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

deny-role1 = You do not have required role!

To log in with Bitbucket, perform the following procedure.

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

To log in with Github, perform the following procedure.

See official OpenShift documentation for more information.