In this article, we will share tips and tricks about understanding Keycloak RedHat SSO Authentication mecanisms.
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 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
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:
◦ This is a browser authentication way from the navigator
◦ The associated flow is browser authentication flow
◦ 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
◦ 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
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.
If the user has the authentication type configured, it will be executed. Otherwise, it will be ignored.
If disabled, the authentication type is not executed.
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
- 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:
When set, a user must change their password.
When set, a user must configure a one-time password generator on their mobile device using either the Free OTP or Google Authenticator application.
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.
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.
The customisation of the authenticator is somewhat described in the keycloak documentation in the authentication SPI section of the server developer guide
The source used to be able to the authenticator flow is provided at:
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.
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
Copy the secret-question.ftl and secret-question-config.ftl files to the themes/base/login directory.
Execute the follow. This will build the example and deploy it
$ mvn clean install wildfly:deploy
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
in your copy, click the « Actions » menu item and « Add Execution ». Pick Secret Question
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)
the secret question is added as mandatory
Also the authentication is updated with secret question mentioned as required
The browser flow is updated with authenticator_custom
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.