Understanding Keycloak RedHat SSO Authentication

In this article, we will share tips and tricks about understanding Keycloak RedHat SSO Authentication mecanisms.

1 Presentation

For each realm, it it is possible to configure Authentication.
There is on the left hand-side an Authentication TAB, that the user can configure.

By default, authentication is configured on a per realm basis.

Configuring authentication means associating a specific authentication flow for each authentication binding

Authentication Binding

Authentication bindings defines the kind of action of actionwhich is going to perform against keycloak.
It can be:
• Authentication using the browser
• Authentication using direct access grant (using REST Call)
• password credential reset
• user registration
• client authentication

Authentication flow

An Authentication flow defines all the steps which are relevant to perform a given authentication.
It is possible to define new authentication flow

2 Authentication TAB selection

The following screen appears when clicking on the authentication TAB.

3 Authentication Binding

Authentication Binding allow to define which flow to use for a specific type of authentication way.
The different authentication ways defined are:
• Browser
◦ This is a browser authentication way from the navigator
◦ The associated flow is browser authentication flow
• Registration
◦ This corresponds to a user registration action
◦ The associated flow is registration authentication flow
• Direct Grant:
◦ This corresponds to a an authentication made from CLI using REST API
◦ The associated flow is direct grant authentication flow
• Reset Credentials
◦ This corresponds to a reset credentials action
◦ The associated flow is reset credential flow
• Clients
◦ This corresponds to client apps authentication against keycloak
◦ The associated flow is client flow

4 Authentication Flow

4.1 Authentication flow presentation

An Authentication is made up of elementary steps, mentioned as Auth Type.

The Auth type step is perfomed according to the Requirement field Value

The requirement type can take following values
Required
This authentication execution must execute successfully. If the user doesn’t have that type of authentication mechanism configured and there is a required action associated with that authentication type, then a required action will be attached to that account. For example, if you switch OTP Form to Required, users that don’t have an OTP generator configured will be asked to do so.

Optional
If the user has the authentication type configured, it will be executed. Otherwise, it will be ignored.

Disabled
If disabled, the authentication type is not executed.

Alternative
This means that at least one alternative authentication type must execute successfully at that level of the flow.

4.2 Browser authentication flow

The first authentication type is Cookie. When a user successfully logs in for the first time, a session cookie is set. If this cookie has already been set, then this authentication type is successful. Since the cookie provider returned success and each execution at this level of the flow is alternative, no other execution is executed and this results in a successful login.

Next the flow looks at the Kerberos execution. This authenticator is disabled by default and will be skipped.

The next execution is a subflow called Forms. Since this subflow is marked as alternative it will not be executed if the Cookie authentication type passed. This subflow contains additional authentication type that needs to be executed. The executions for this subflow are loaded and the same processing logic occurs

The first execution in the Forms subflow is the Username Password Form. This authentication type renders the username and password page. It is marked as required so the user must enter in a valid username and password.

The next execution is the OTP Form. This is marked as optional. If the user has OTP set up, then this authentication type must run and be successful. If the user doesn’t have OTP set up, this authentication type is ignored.

4.3 Direct Authentication Grant flow

With Direct Grant Authentication Flow, it is required to enter username and a password.
OTP is optional if it has been configured.

4.4 Registration Flow

When performing user registration, the user has to provide:

• User information
• Profile
• Password
• And captcha (if enabled)

4.5 Reset Credentials

When resetting credentials, the user is going through the following steps
• Indicate the user name
• indicate the email address, where to send a temporary password
• reset password

4.6 First Broker Login Flow

First Login flow is the flow used when authenticating external IDP using
the openid protocol.
As can be seen below, are listed all the actions that are performed with their associated requirement value.

Below is an example of an identity provider, using first broken login flow as authentication flow.

4.7 Client authentication flow

Below is the client authentication flow.
It showcases that a client needs to authenticates against keycloak using one of the 4 Flows mentioned:
• client/client secret
• signed jwt
• signed jwt with secret key
• X509 certificate

5 Required Actions

Required Actions are tasks that a user must finish before they are allowed to log in. A user must provide their credentials before required actions are executed. Once a required action is completed, the user will not have to perform the action again. Here are explanations of some of the built-in required action types:

Update Password
When set, a user must change their password.

Configure OTP
When set, a user must configure a one-time password generator on their mobile device using either the Free OTP or Google Authenticator application.

Verify Email
When set, a user must verify that they have a valid email account. An email will be sent to the user with a link they have to click. Once this workflow is successfully completed, they will be allowed to log in.

Update Profile
This required action asks the user to update their profile information, i.e. their name, address, email, and/or phone number.

Admins can add required actions for each individual user within the user’s Details tab in the Admin Console.

6 Customising authenticator flow

In this section, we are investigating how it is possible to customize the authenticator the authenticator flow.

6.1 Reference

The customisation of the authenticator is somewhat described in the keycloak documentation in the authentication SPI section of the server developer guide
• https://www.keycloak.org/docs/latest/server_development/index.html#_auth_spi

The source used to be able to the authenticator flow is provided at:
• https://github.com/keycloak/keycloak/tree/4.7.0.Final/examples/providers/authenticator

Note:

Keycloak authenticator example is missing from the 5.0 keyclok examples git. The last one available is 4.7.0 A JIRA ticket has been created.
• https://issues.jboss.org/browse/KEYCLOAK-9871

6.2 Installing the authenticator example

You need to download the authenticator from keycloak git 4.7.0

6.3 Deploying the customized authenticator flow

step 1
Copy the secret-question.ftl and secret-question-config.ftl files to the themes/base/login directory.

step2

Execute the follow. This will build the example and deploy it
$ mvn clean install wildfly:deploy

step3

Go to the Authentication menu item and go to the Flow tab, you will be able to view the currently defined flows. You cannot modify an built in flows, so, to add the Authenticator you have to copy an existing flow or create your own. Copy the « Browser » flow.

And now here is the new authentication flow

Step 4

step5

in your copy, click the « Actions » menu item and « Add Execution ». Pick Secret Question

Click “save”

step 6

Next you have to register the required action that you created. Click on the Required Actions tab in the Authentication menu

Your new required action should now be displayed and enabled in the required actions list
(which is the case below)

step 7

the secret question is added as mandatory

Also the authentication is updated with secret question mentioned as required

step 8

Binding modification
The browser flow is updated with authenticator_custom

step 9

authentication (1) first step
It is asking for username/password for the first authentication.

Authentication (2) – It has asking for the secret question

and the user get authenticated.