Keycloak configuration documentation

Introduction

This document is dedicated to the configuration of keycloak for proPilot, but the same process can be used for other applications.

proPilot requirements to interact with Keycloak

The following keys will be used in this document: they are required to setup Keycloak configuration in proPilot (see sample configuration at the end of this document).
Each key will be detailed in the following sections.

KEYCLOAK_DOMAIN_NAME : Complete Domain Name
REALM_NAME : Name of the Realm
ADMIN_CLI_CLIENT_SECRET : Client Secret of the “admin-cli” client.
CLIENT_ID : Client id to use to authenticate users
AUDIENCE : Audience Name (More info about audience here https://github.com/keycloak/keycloak-documentation/blob/main/server_admin/topics/clients/oidc/con-audience.adoc )

End to end configuration of a new Realm for proPilot

Creation of a new Keycloak Realm: Select realm → Add realm

In keycloack, from the admin account, create a new realm using

Create a new Realm

Name: “proPilot” (or another name if your company uses a custom name, but in this document we’ll use proPilot)

This name is the technical name.

Enabled: ON
Click on “Create”.

Configure General information

(left menu section) “Configure” → (menu item) “Realm settings” → (tab) “General”

Display name: proPilot
HTML display name: proPilot
Click on save.

The name will be used in the email generate by Keycloak

Configure login

In the login tab

User registration: OFF
Forgot password: ON
Remember me: ON

Email settings

Email as username (depends on your organisation)
Login with email: ON
Duplicate emails: OFF
Verify email: OFF

→ Click on “save”.

Configure SMTP server

(left menu section) “Configure” → (menu item) “Realm settings” → (tab) “Email”

Configure SMTP server

By default, in UAT environment, you may configure a Mailcatcher.

From: noreply@yourCompany.com

Activate proPilot Themes

By defaut, keyCloak provides a restricted set of themes, but you may add custom themes.
See official documentation:
https://www.keycloak.org/docs/latest/server_development/#_themes

Do not hesitate to contact the proPilot team to obtain a custom theme, if you want to keep the proPilot look an feel.

→ Click on “save”.

Enable internationalization

(left menu section) “Configure” → (menu item) “Realm settings” → (tab) “Localization”

Enable the internationalization: ON
Activate “Supported Locales”: en & fr
Default locale: en (by default) fr (for french client)

→ click on save

Secure Realm

(left menu section) “Configure” → (menu item) “Realm settings” → (tab) “Security defense” → (sub-tab) “Brute force Detection”

Select your preferred strategy and customize the default values only when necessary

→ Click on save.

Configure Authentification with password policy

(left menu section) “Configure” → (menu item) “Authentication” → (tab) “Policies“ → (sub-tab) “Password policy”

Standard proPilot required password policy is as follow

minimum password length 16 characters
At least one upper case character
At least one lower case character
At least one number
Not user name
Not email
Not recently used (3 last passwords)

Create a keyCloak client for proPilot

(left menu section) “Manage” → (menu item) “Clients” → (tab) “Clients list“

Create a new client in your realm
Set a client id (unique)

Click “Next”
Client authentication: OFF
Authorization: OFF
Standard Flow Enabled: ON
All other flows (e.g. Direct access grant must be disabled): OFF

Specify the “valid redirected URLs”, which specifies the pattern of valid client urls (e.g. http://localhost:4200/* means that all uris beginning by http://localhost:4200/ are considered as valid addresses to redirect to.)
Specify as well the Base URL, which must be the entry point of the business application front-end (e.g. http://propilot.dev.dfakto.com/ ). This base URL will be used in the emails sent by keyCloak to link back to the business application.
Set Web origins (you can use + or even * )

→ Click “Save”

Update the “admin-cli” client

This client is used to access keyCloak through REST api calls (e.g. external applications like proPilot).

To configure clients, go to the administration console

Clients (left menu).
on the correct client.
press the “edit” button.
Edit the “admin-cli” client

Note that the name must not be changed. It is hard-coded in the C# library we are using right now

In the Settings tab

Activate the client authentication
Enable Service Account roles (necessary for API calls from our applications) and disable other flows
Click Save

In the Credentials tab

If this tab its not visible, ensure that the client authentication is enabled (as shown above), and that you clicked the “save” button in the settings tab, as requested above

Retrieve Secret content and paste it in your external application parameters (e.g. ProPilot configuration)

In the Service Account Roles tab

(If this tab is not visible, ensure Service Account Flow is enabled in the settings tab, as requested above)

select the “by clients” filter and use the search field to add the roles listed below

make sure to have the following Assigned Roles
- “manage-users”
- “query-users”
- “view-users”
- “view-realm“

Create the first “admin” user in Keycloak

(left menu section) “Manage” → (menu item) “Users”

This main user is required to be able to log in ProPilot the first time.

Add user information: Username “Adm”, First Name: “Administrator”, last name can be left empty.

Email: email address of the admin account (can be left empty).
Email Verified: ON

Press the “Save” button

Set password, and do not mark it as temporary or the user will have to change it at next logon)

Please apply dFakto security standards during the creation of first admin password. Do not use the same password for many admin accounts.

Sample configuration for Backend and Frontend in proPilot

Configuration files of proPilot will be described again in the dedicated document, but we give the specific keycloak section here below.
In the configuration file, replace the [[CONFIGKEY]] by the actual value retrieved from Keycloak (described in this document).

Example:

Backend & service

XML

<add key="propilot:identityServerHost" value="https://[[KEYCLOAK_DOMAIN_NAME]]/auth/realms/[[REALM_NAME]]" />
<add key="propilot:keycloak:identityServer" value="https://[[KEYCLOAK_DOMAIN_NAME]]" />
<add key="propilot:keycloak:identityServerSecret" value="[[ADMIN_CLI_CLIENT_SECRET]]" />
<add key="propilot:keycloak:audience" value="[[AUDIENCE]]" />
<add key="propilot:keycloak:clientId" value="[[CLIENT_ID_OF_PROPILOT_CREATED_IN_KEYCLOAK]]" />

Frontend

JSON

{
  "applicationName": "Propilot",
  "environment": "dev",
  "sentryDsn": "https://d0f23c72bb804fc59cbded8b30162a6f@sentry.dfakto.com/20",
  "lang": "fr",
  "languagesAvailable": [
    "en",
    "fr"
  ],
  "client": "dFakto",
  "authConfig": {
    "responseType": "code",
    "scope": "openid email profile",
    "showDebugInformation": true,
    "clientId": "[[CLIENT_ID]]",
    "issuer": "https://[[KEYCLOAK_DOMAIN_NAME]]/auth/realms/[[REALM_NAME]]",
    "strictDiscoveryDocumentValidation": false,
    "silentRefresh": true,
    "useHttpBasicAuth": true
  }
}

[data-colorid=f1sj8qcywq]{color:#ff5630} html[data-color-mode=dark] [data-colorid=f1sj8qcywq]{color:#cf2600}Introduction