Skip to content

Koldan Installation Procedures

Keycloak

After installing Keycloak, several settings must be made to allow Koldan to use it.

Create Realm

Start by creating a new realm named: dixilang. We will configure it further later.

Create Realm Roles

There are 2 roles that need to be created:

  • koldan-user
  • koldan-admin

Create them under the newly created realm.

Create Clients

koldan-api-grpc

  • Client Type: OpenID Connect
  • Client ID: koldan-api-grpc
  • Client Name: Koldan Desktop
  • Client Authentication: ON
  • Authentication Flow: Standard flow, Direct access grants and Service accounts roles.
  • Home URL: <koldan HTTP server URL>
  • Valid Redirect URIs:
  • koldan://*
  • <koldan HTTP server URL>/appredirect.html
  • Web Origins: (empty)

After creating client, set these additional settings:

  • Advanced: Proof Key for Code Exchange (PKCE) Code Challenge Method: S256

koldan-api-http

  • Client Type: OpenID Connect
  • Client ID: koldan-api-http
  • Client Name: Koldan Console
  • Client Authentication: ON
  • Authentication Flow: Standard flow, Direct access grants and Service accounts roles.
  • Home URL: <koldan HTTP server URL>
  • Valid Redirect URIs:
  • <koldan HTTP server URL>/*
  • Web Origins: (empty)

After creating client, set these additional settings:

  • Advanced: Proof Key for Code Exchange (PKCE) Code Challenge Method: S256
  • In Service Account Roles tab, Click Assign Role, filter by Client Roles and choose query-realms.

koldan-engine

  • Client Type: OpenID Connect
  • Client ID: koldan-engine
  • Client Authentication: ON
  • Authentication Flow: Standard flow and Service accounts roles.
  • Home URL: (empty)
  • Valid Redirect URIs: (empty)
  • Web Origins: (empty)

After creating client, set these additional settings:

  • In Service Account Roles tab, Click Assign Role, and choose koldan-user.

Client Secrets Storage

Store clientId and clientSecret for client per service.

You can also set them already on the service properties, using: koldan.keycloak.client-id and koldan.keycloak.client-secret.

Realm Settings

Go to the realm settings and start to apply configurations by tabs:

Realm Settings: General

  • Change the Display Name to Koldan
  • Optionally change the HTML Display Name to <h1>Site Name</h1>

Realm Settings: Login

  • Optionally enable User registration if needed

Realm Settings: Security defenses

  • Navigate to sub-tab Brute force detection
  • Set Brute Force Mode to Lockout Temporarily

Realm Settings: Sessions

  • Set SSO Session Idle to 31 Days
  • Set SSO Session Max to 31 Days

Realm Settings: Tokens

  • Access Token Lifespan: 15 Minutes

Realm Settings: User Registration

  • In Default Roles, use the Assign role option to set the default role to koldan-user

Authentication

In order to support accounts without validated email, it is required to shut off Verify Profile and Verify Email step on authentication.

Go to Authentication -> Required Actions and search Verify Profile and Verify Email and make it disabled.

User Federation: LDAP

In order to allow users in the organization to connect to Realm through their LDAP account, a new User Federation of LDAP type needs to be created.

LDAP Configurations

General options:

  • UI display name: ldap
  • Vendor: Active Directory

Connection and authentication settings:

  • Connection URL (e.g): ldap://DIXISBSSRV.DIXILANG.local:389
  • Bind Type: simple
  • Bind DN: Open Command Line and use whoami /fqdn to achieve full DN (e.g: CN=Ploni Almoni,OU=Workers,DC=DIXILANG,DC=local)
  • Bind credentials: Use the password for the DN (i.e your LDAP password)

LDAP searching and updating:

  • Edit Mode: READ_ONLY
  • Users DN: <DN required for users> (e.g: OU=Domain Users,DC=DIXILANG,DC=local)
  • Pagination: ON

Synchronization settings: * Batch size: set to 250

Advanced settings:

  • Trust Email: ON

Find LDAP server

nslookup -type=all _ldap._tcp

Username is not in CN

If the customer LDAP not using the default cn as usernames, we need to find out what attribute on the user object is the username, we can do it by running this PowerShell command on one of the users (or ours):

get-aduser -Identity USERNAME -properties *

If not dn, it is usually sAMAccountName.

Go to the Settings tab and set Username LDAP attribute to the correct attribute key.

After that, go to Mappers tab and edit username mapper LDAP Attribute to the correct attribute key.

Use LDAP Groups

To associate user groups from LDAP to Keycloak, a new mapper needs to be created.

Go to the Mappers tab and create new mapper of type role-ldap-mapper.

  • Name: roles mapper
  • LDAP Roles DN: <Base DN for roles> (e.g: OU=Workers,DC=DIXILANG,DC=local)

After the creation of the mapper, enter the mapper and execute the action: Sync LDAP roles to Keycloak.

If sync fails you can filter to sync only the dedicated group, for exmaple - sync groups thats starts with HMC:

(&(objectClass=group)(cn=HMC*))

To associate an LDAP role with a Koldan role, use a composite role.

For example, if there is an Administrators role in LDAP, make it a composite role and attach the koldan-admin role to it by choosing the role in Realm Roles, going to Actions (right corner), and selecting Associate Roles.

Grafana Client

Create a client in Keycloak with the following settings:

  • Client Protocol: openid-connect
  • Client ID: grafana
  • Client authentication: ON
  • Authorization: OFF
  • Standard Flow Enabled: ON
  • Direct Access Grants Enabled: ON
  • Implicit Flow Enabled: OFF
  • Service accounts roles: OFF
  • Root URL: http://<SERVER_IP>:3000
  • Valid Redirect URIs: http://<SERVER_IP>:3000/login/generic_oauth
  • Web Origins: http://<SERVER_IP>:3000
  • Admin URL: http://<SERVER_IP>:3000

In the client scopes configuration, ensure Default on:

  • email
  • offline_access
  • profile
  • roles

For role mapping to work with the example configuration above, you need to create the following roles and assign them to users:

  • grafana-viewer
  • grafana-master

To log into grafana with keycloak - assign the role you want to the user or group

  • user -> assign role -> grafana-admin

Troubleshoot

get-aduser command not found problem

Open powershell with administrator user and run the followin command:

Install-WindowsFeature -Name “RSAT-AD-PowerShell” -IncludeAllSubFeature

Import the Active Directory PowerShell Module

Get-Module -Name ActiveDirectory -ListAvailable

Find DN without login permissions to app user

Ensure Get-ADUser command in powershell

Install-WindowsFeature -Name "RSAT-AD-PowersSell"

and run

Get-ADUser -Identity "username"

Find LDAP server without login permissions to app user

open CMD

nltest /dclist:yourdomain.com