Reseller Keycloak Quick Installation Guide

Introduction

This document list all the features related to Synergy and Focus

Keycloak is an Open-source product which allows Single Sign-On (SSO) and enables Identity and Access Management integration to allow for a quick, safe, and secure integration of authentication within modern applications.

When a cluster is generated via the Getvisibility reseller dashboard, it creates a Keycloak instance within the cluster for managing authentication.

When this cluster is created, a default Keycloak Realm configuration is loaded, and only a few installation steps are required.

This document describes the remaining installation steps required to complete the Keycloak installation setup.

Below are the steps involved in configuring Keycloak, and you may choose to skip the Optional steps based on your preferences and products.

Logging into Keycloak admin panel

The Keycloak admin URL will consist of the following components:

• The domain that has been configured for your reseller to access the application (E.g. my-reseller.net or 10.10.121.127)

• The service path (E.g. auth for Keycloak)

• The keycloak admin path /admin/master/console

An example of the above might look something like this:

https://my-reseller.net/auth/admin/master/console

Once you have entered the correct address for your cluster Keycloak instance following the above guidelines, you should be able to login to the Keycloak admin dashboard using the following details:

Username: admin

Password: admin

The access protocol should always be https.

The domain in the example above (E.g. my-reseller.net) might not be applicable if a domain is not configured, in which case you would need to use the server IP address (E.g. 10.10.121.127)

Once logged into the portal, there are a few steps to complete in order to configure Keycloak.

Completing the Realm Configuration

In Keycloak, a Realm is a top level authentication domain which contains an isolated authentication configuration.

A good way to imagine this is that each Keycloak Realm might each represent a different environment.

We need to create a Realm for managing our cluster authentication, please follow the steps below in order to do this:

1. Click on the left-side menu item Realm Settings.

1. This will load the Gv Realm Settings → General tab, enter your desired user-friendly reseller name into both the Display name and HTML Display name fields

1. Click the Save button to commit these changes to the Realm Settings.

Completing the Dashboard Client Configuration

1. Click on the Clients menu item on the left-side menu, this should load a list of authentication clients

   

2. Click on Edit (or click on the name link) on the item labelled dashboard in order to load the client

   

3. Open the dropdown for Login Theme and select the theme created for your reseller (E.g. my-reseller-theme)

   

4. Update the Valid Redirect URIs to include the URL you have configured for the Dashboard UI (remember to click the + plus icon after entering the value). This will allow Keycloak to redirect back to your Dashboard UI after authenticating

   

5. Update the Web Origins to include the URL you have configured for the Dashboard UI (remember to click the + plus icon after entering the value). This will allow CORS endpoint calls to Keycloak from the Dashboard UI.

   

6. Click the Save button at the bottom of the screen

(Required for Synergy) Setting up a default Agent user

This step is important and required is you are using Synergy Product for the agent to work correctly.

Please follow these simple steps in order to configure the default user for the Desktop agent.

1. Click on the Users menu item on the left-side menu, this should load the Users list

   

2. Click the Add user button in the top right to open the Add user screen

   

3. It’s only necessary to complete two fields on this form; The Username field should contain agent, and the Email field should contain [e-mail]:

   

4. Click the Save button at the bottom of the screen

(Optional) Completing the Agent Client Configuration

This step is optional if you are using Synergy Product and not required if you are using Focus

1. Click on the Clients menu item on the left-side menu, this should load a list of authentication clients

   

2. Click on Edit (or click on the name link) on the item labelled agent in order to load the client

   

3. Update the Valid Redirect URIs value (default is https://localhost:80) to a secure address that you know is not vulnerable or exposed. This is a required field and requires at least one value, so while we have set it to a temporary value, it’s encouraged to change this to something internal.

   

4. Click the Save button at the bottom of the screen

(Optional) Completing the User Federation Configuration

The authentication protocol that the customer decides to use is different per use case. Below is some guidance on how to configure a User Federation in Keycloak.

Configuring the User Federation

Configuring the User Federation

1. Click on the User Federation menu item on the left-side menu, this should load a list of configured user federations

   

2. Click on Edit (or click on the name link) on the item labelled ldap in order to load the LDAP (Lightweight Directory Access Protocol) configuration

   

3. Update the Connection URL field to reflect the LDAP server address where the Active Directory is hosted.

   

4. Update the Users DN field (see the above image) to contain the Full DN of the LDAP tree where your users are

5. Click on the button Test connection to test the connection from the Keycloak instance to the LDAP server address. This should succeed quickly, and if it hangs, there is a possibility that the LDAP server is not allowing access from the Keycloak instance server address, or you may need to use the Public IP address of the LDAP server.

   

6. Update the Bind DN field to reflect the relevant username used to access the LDAP server

   

7. Update the Bind Credential field (see the above image) to contain the relevant password used to access the LDAP server

8. (Optional) Click on the Accordion option Sync Settings in order to set up automatic synchronization of users from the LDAP Active Directory to Keycloak. You are able to configure the auto-synchronization settings here, if you like.

   

9. Click the Save button at the bottom of the screen

Synchronizing the Users to Keycloak DB

In order to get the users into the Keycloak DB, we need to synchronize the users for the first time (before the automatic synchronization happens, if applicable).

This is one simple step:

1. Click the button Synchronize all users in order to immediately fetch all of the LDAP Active Directory users and load them into the Keycloak instance DB

Synchronizing all users may take some time, please be patient.

Troubleshooting Keycloak LDAP integration

Usually any issues which occur during the LDAP Active Directory configuration process above will be related to Network accessibility concerns or authentication credentials being incorrect.

However, if you require any additional support or your problem is not easily resolved by troubleshooting Network communications and authentication details, please reach out to our support at [e-mail]