Configure the Master realm

Most Keycloak configurations are realm-specific. Before modifying any configuration, make sure the correct realm is select in the top left dropdown. For now, we want to configure the master realm which is shown as “Keycloak” there.

1. Security settings

Out of the box, Keycloak does not enforce many security mechanisms regarding authentication, so we may want to enable some of them. The settings we enable here can also be enabled for the other realms we will configure afterwards.

Brute force detection

First go to Realm settings in the left menu, select the Security defenses tab at the top and the Brute force detection sub-tab.

Brute force detection is Disabled by default. Keycloak offers different lockout presets, we recommend setting it to Lockout temporarily and adjusting the Max login failures and Failure reset time to your needs, but stricter policies are perfectly acceptable 😁.

If you ever get locked out of the master realm because all user accounts are in permanent lockout, you always have the possibility to connect to the Keycloak database, delete all master realm users, and recreate a first admin as during the Keycloak install. The required steps are explained in this stackoverflow post.

2-factor authentication

Keycloak supports 2-factor authentication using authenticator app OTP out of the box. Parameters for the OTP can be configured on the Authentication page, in the Policies tab and OTP Policy sub-tab.

1. Each user may choose to enable 2-factor authentication for their account by selecting Manage account for the top right dropdown and opening the Account security and Signing in page from the account page left menu.

   

   They may now click Set up Authenticator application to enroll their authenticator app.

   

2. An admin may force a user to enroll an authenticator app by selecting the Users page from the left menu, finding the user they want and from their Details page, adding the Configure OTP “Required user actions”.

   

3. Finally, you may force any new user in a realm to “Configure OTP” by opening the Authentication page, opening the Required actions tab and turning the “Set as default action” switch On for Configure OTP

   

Password policy

You may also define password policies to enforce a minimal length or special characters in realm user passwords. You may configure this on the Authentication page, in the Policies tab and Password policy sub-tab.

HTTP security headers

By default, Keycloak defines a few HTTP security headers. You may want to change the default settings to match your organisation’s security policy. This can be done on the Realm settings page, in the Security defenses tab and the Headers sub-tab.

The headers you configure here apply to pages served in the context of a specific realm and should be repeated for all realms. Also, some pages are served as static files, directly by Quarkus (the engine on which Keycloak is built). The settings configured here do not apply to these files. This is for example the case for the Olvid Management Console. Security headers can be configured for these pages by modifying the conf/quarkus.properties file inside your Keycloak installation folder. Keycloak needs to be restarted before changes you make to this file are taken into account.

2. Create other Keycloak admins

For now we have only created one admin user in the master realm. In case you want to add other admins:

1. open the Users page in the left menu and press Add user

   

2. enter a Username and any other field you want to add

   

   • The Email verified switch allows telling Keycloak that email verification is not required for this user

   • The Required user actions dropdown at the top allows to define actions the new user will need to take after he first signs in. Not need to set Update password yet as it will be set by default when creating a password for this user.

     

3. now press Create to create the user and go to the Credentials tab to set a password.

   

4. press Set password and enter the temporary password for the new user. Leaving the Temporary switch on will require the user to change this password when they first sign in.

   

3. Sending E-mails (optional)

When creating users and admin users from the Olvid Management Console it is possible to have them receive their temporary password by email. In order to do so, Keycloak must be configured to send emails. Note that the master realm’s email configuration will be used for all emails sent through the Olvid Management Console.

1. open the Realms settings page from the left menu and select the Email tab.

   

2. fill in the required configuration information, including appropriate credentials if authentication is required

   

   If you get the same warning as on the screenshot above, you simply need to configure an email address for the user you are currently logger in as.

3. you may press Test connection to validate that Keycloak can indeed connect to the SMTP server
4. when everything is ready, do not forget to press Save