Chapter 6. Authentication

Here’s an explanation of each policy type:

There are two different algorithms to choose from for your OTP generators. Time Based (TOTP) and Counter Based (HOTP). For TOTP, your token generator will hash the current time and a shared secret. The server validates the OTP by comparing all the hashes within a certain window of time to the submitted value. So, TOTPs are valid only for a short window of time (usually 30 seconds). For HOTP a shared counter is used instead of the current time. The server increments the counter with each successful OTP login. So, valid OTPs only change after a successful login.

TOTP is considered a little more secure because the matchable OTP is only valid for a short window of time while the OTP for HOTP can be valid for an indeterminate amount of time. HOTP is much more user friendly as the user won’t have to hurry to enter in their OTP before the time interval is up. With the way Red Hat Single Sign-On has implemented TOTP this distinction becomes a little more blurry. HOTP requires a database update every time the server wants to increment the counter. This can be a performance drain on the authentication server when there is heavy load. So, to provide a more efficient alternative, TOTP does not remember passwords used. This bypasses the need to do any DB updates, but the downside is that TOTPs can be re-used in the valid time interval. For future versions of Red Hat Single Sign-On it is planned that you will be able to configure whether TOTP checks older OTPs in the time interval.

Red Hat Single Sign-On comes with a certain number of built-in flows. These flows cannot be modified, but the requirements can be modified to suit your needs.

This section does a walk-through of the built-in browser login flow. In the left drop-down list select browser to come to the screen shown below:

If you hover over the tooltip (the tiny question mark) to the right of the flow selection list, this will describe what the flow is and does.

The Auth Type column is the name of authentication or action that will be executed. If an authentication is indented this means it is in a sub-flow and may or may not be executed depending on the behavior of its parent. The Requirement column is a set of radio buttons which define whether or not the action will execute. Let’s describe what each radio button means in this context.

This section explains in greater depth how flows work, and how to create your own flows. Note that there are important functionality and security considerations when designing your own flow. A badly created flow could either let no one log in, let users in with less verification than you would like, or simply result in an error.

To create a flow, you can either:

When creating a new flow, you will have to create a top level flow

With the following options:

Once the flow is created, in addition to the New and Copy buttons, you now have, Delete, Add execution and Add flow.

What a flow finally does is determined by the structure of the flow and sub-flows, the executions in those flows, and the requirements set on the sub-flows and the executions.

Executions can be added with the Add execution button. Executions can have a wide variety of actions, from sending a reset email to validating an OTP. If you hover over the tooltip (the tiny question mark) next to Provider, this will describe what the execution does.

These can be divided into automatic executions and interactive executions. Automatic executions are similar to the Cookie execution, and will automatically perform their action when they are encountered in the flow. Interactive executions will halt the flow, usually to get some user input. Executions that execute successfully will get the success status. This is important, because this is part of whether a flow is successful or not. For example, an empty Browser flow would not allow anyone to log in. For that it would need at least one execution that successfully evaluates, for example a Username Password Form that is corrected filled and submitted.

Sub-flows can be added in top level flow with the Add flow button, which opens a Create Execution Flow page that is very similar to the Create Top Level Form page. The only difference is that the Flow Type can be either generic (like before), or form. The form type is used to construct a sub-flow that generates a single form for the user, like what is done for the built-in Registration flow. Sub-flows are a special type of execution that evaluate as successful depending on how the executions they contain evaluate (and this includes the evaluation of their contained sub-flows). And the logic of this evaluation depends on the Requirement of each execution and sub-flow.

Fully understanding this requires a more complete explanation of how requirements work when evaluating a flow, and this also applies to sub-flows. Refer to the execution requirements section above for more details.

Note that after adding an execution, you should check that the Requirement is set to the correct value. Even if there is only a single possible Requirement, it can happen that it is not set.

When constructing a flow, all elements added to the flow will have an Actions menu on the right-hand side. All elements added to the flow have a Delete option in this menu to remove it from the flow. Executions can contain a Config menu option to configure the execution, as is the case for the Identity Provider Redirector. Sub-flows can also have executions and sub-flows added to them, with their Add execution and Add flow menu options.

Finally, since the order of execution is important, you can move executions and sub-flows up and down within their respective flows with the up and down buttons that are set to left of their name.

To illustrate the creation of flows, this section describes the creation of a more advanced browser login flow. The purpose of this flow is to allow a user to choose between logging in in a password-less manner using WebAuthn, and a two-factor authentication with password and OTP. The flow to create is similar to the standard browser login, but diverges when reaching the username selection. Instead of copying the flow however, you’ll be creating the flow from the start:

The Username form is similar to "Browser" flow’s Username Password Form, but only asks for a username, allowing a user to perform a password-less login. However, note that this inevitably allows a user enumeration attack on your Red Hat Single Sign-On server. This is an unavoidable security risk for the convenience, so the flow should make sure that an attacker cannot just have to guess a password to be able to enter.

The final flow that is produced is the following:

After entering the username, the way this flow works is the following:

It is important to note that since the WebAuthn Passwordless execution is set to Alternative instead of Required, this flow will never ask the user to register a WebAuthn credential. For a user to have a Webauthn credential, that user must have a required action added by an administrator. This is done first by making sure that the Webauthn Register Passwordless required action is enabled in the realm (see the WebAuthn documentation), and then by setting the required action by using the Credential Reset part of a user’s Credentials management menu.

Creating a more advanced flow such as this one can have some subtle side effects. For example, if you were to enable the ability to reset the password for the user, then this would be accessible from the password form. In the default "Reset Credentials" flow, the user has to enter his username. Since he’s already entered his username earlier in the "Browser Password-less" flow, this would be unnecessary for Red Hat Single Sign-On, and a sub-optimal in terms of user experience. To correct this, you could:

This is platform dependent. Exact steps depend on your OS and the Kerberos vendor you’re going to use. Consult Windows Active Directory, MIT Kerberos and your OS documentation for how exactly to setup and configure Kerberos server.

At least you will need to:

sudo kadmin.local

Then add HTTP principal and export his key to a keytab file with the commands like:

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

The Keytab file /tmp/http.keytab will need to be accessible on the host where Red Hat Single Sign-On server will be running.

You need to install a kerberos client on your machine. This is also platform dependent. If you are on Fedora, Ubuntu or RHEL, you can install the package freeipa-client, which contains a Kerberos client and several other utilities. Configure the kerberos client (on Linux it’s in file /etc/krb5.conf ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on. For the example realm MYDOMAIN.ORG you may configure the domain_realm section like this:

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

Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which Red Hat Single Sign-On server is running. For production, it’s ideal if it’s readable just by this process and not by someone else. For the MIT Kerberos example above, we already exported keytab to /tmp/http.keytab . If your KDC and Red Hat Single Sign-On are running on same host, you have that file already available.

Clients need to install kerberos client and setup krb5.conf as described above. Additionally they need to enable SPNEGO login support in their browser. See configuring Firefox for Kerberos if you are using that browser. URI .mydomain.org must be allowed in the network.negotiate-auth.trusted-uris config option.

In a Windows domain, clients usually don’t need to configure anything special as IE is already able to participate in SPNEGO authentication for the Windows domain.

Kerberos 5 supports the concept of credential delegation. In this scenario, your applications may want access to the Kerberos ticket so that they can re-use it to interact with other services secured by Kerberos. Since the SPNEGO protocol is processed in the Red Hat Single Sign-On server, you have to propagate the GSS credential to your application within the OpenID Connect token claim or a SAML assertion attribute that is transmitted to your application from the Red Hat Single Sign-On server. To have this claim inserted into the token or assertion, each application will need to enable the built-in protocol mapper called gss delegation credential. This is enabled in the Mappers tab of the application’s client page. See Protocol Mappers chapter for more details.

Applications will need to deserialize the claim it receives from Red Hat Single Sign-On before it can use it to make GSS calls against other services. Once you deserialize the credential from the access token to the GSSCredential object, the GSSContext will need to be created with this credential passed to the method GSSManager.createContext for example like this:

// 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 that you also need to configure forwardable kerberos tickets in krb5.conf file and add support for delegated credentials to your browser.

In the Kerberos V5 protocol, the realm is a set of Kerberos principals defined in the Kerberos database (typically LDAP server). The Kerberos protocol has a concept of cross-realm trust. For example, if there are 2 kerberos realms A and B, the cross-realm trust will allow the users from realm A to access resources (services) of realm B. This means that realm B trusts the realm A.

The Red Hat Single Sign-On server has support for cross-realm trust. There are few things which need to be done to achieve this:

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

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

The regular expression filtering is applicable only if the Identity Source is set to either Match SubjectDN using regular expression or Match IssuerDN using regular expression.

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:10.0">
	....
    <server name="default-server">
	    <https-listener name="default"
                        socket-binding="https"
                        security-realm="ssl-realm"
                        verify-client="REQUESTED"/>
    </server>
</subsystem>

When an HTTP request is sent directly to Red Hat Single Sign-On server, the JBoss EAP undertow subsystem will establish an SSL handshake and extract the client certificate. The client certificate will be then saved to the attribute javax.servlet.request.X509Certificate of the HTTP request, as specified in the servlet specification. The Red Hat Single Sign-On X509 authenticator will be then able to lookup 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, it may be the proxy server which extracts the client certificate and establishes the mutual SSL connection. A reverse proxy usually puts the authenticated client certificate in the HTTP header of the underlying request and forwards it to the back end Red Hat Single Sign-On server. In this case, Red Hat Single Sign-On must be able to look up the X.509 certificate chain from the HTTP headers instead of from the attribute of HTTP request, as is done for Undertow.

If Red Hat Single Sign-On is behind a reverse proxy, you usually need to configure alternative provider of the x509cert-lookup SPI in RHSSO_HOME/standalone/configuration/standalone.xml. Along with the default provider, which looks up the certificate from the HTTP header, we also have two additional built-in providers: haproxy and apache, which are described next.

<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:3.0">
...
            <logger category="org.keycloak.authentication.authenticators.x509">
                <level name="TRACE"/>
            </logger>
            <logger category="org.keycloak.services.x509">
                <level name="TRACE"/>
            </logger>

WARNING: Don't use RequestDumpingHandler or TRACE logging in production.

$ curl https://[host][:port]/auth/realms/master/protocol/openid-connect/token \
       --insecure \
       --data "grant_type=password&scope=openid profile&username=&password=&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" \
       -E /path/to/client_cert.crt \
       --key /path/to/client_cert.key

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

After registering a WebAuthn authenticator, the user carries out the following operations assuming that authentication flow configuration above with the conditional subflow using WebAuthn Authenticator was used:

When registering a WebAuthn authenticator, Red Hat Single Sign-On verifies an attestation statement generated by this WebAuthn authenticator. On this verification process, Red Hat Single Sign-On validates this attestation statement’s trustworthiness. It requires trust anchor’s certificates. Red Hat Single Sign-On uses the Keycloak truststore so that you need to import these certificates onto it in advance.

If you want to omit this attestation statement trustworthiness validation, please disable this truststore or set the WebAuthn policy’s configuration item "Attestation Conveyance Preference" to "none".

WebAuthn is often used for two-factor authentication, however it can be desired to use it also as first factor authentication. In this case, a user with passwordless WebAuthn credential will be able to authenticate to Red Hat Single Sign-On without a password. Red Hat Single Sign-On allows to use WebAuthn as both the passwordless and two-factor authentication mechanism in the context of a single realm and even in the context of a single authentication flow.

Administrator may typically require that Security Keys registered by users for the WebAuthn passwordless authentication must meet different (usually stronger) requirements. For example, those security keys may require users to authenticate to that security key using a PIN, or the security key should be attested with stronger certificate authority.

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