Keycloak configuration

How to complete the Keycloak installation setup.

Introduction

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.

Below are the steps involved in configuring Keycloak, and you may choose to skip the Optional steps.

---

Logging into Keycloak admin panel

The Keycloak admin URL will consist of the following components:

• The domain that has been configured for the 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 the correct address has been entered for the cluster Keycloak instance following the above guidelines, it should be possible to login to the Keycloak admin dashboard using the following details:

This is the default username and password for the initial login to Keycloak. Please ensure that it is changed!

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 the server IP address needs to be used (e.g. 10.10.121.127)

Once logged into the portal, there are some additional 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. For example, each separate Keycloak Realm might represent a different environment.

A Realm needs to be created to managa the cluster authentication:

1. Click on the left-side menu item Realm Settings. Make sure that the gv realm is selected in the top left, not master.

Keycloak main screen.

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

Keycloak Ream Settings.

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

Do not change the content of Realm ID field, it has to be gv.

---

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.

Keycloak clients dashboard.

1. Click on the name link of the item labeled dashboard to navigate to its client configuration page.

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

1. Update the Valid Redirect URIs to include the URL that has been configured for the Dashboard UI (remember to click the + plus icon after entering the value). This will allow Keycloak to redirect back to the Dashboard UI after authenticating.

1. Update the Web Origins to include the URL that has been 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.

1. Clear the Front-channel logout URL field’s content. This way, instead of the “you are getting logged out” screen, it will go straight to the login page upon logout. Alternatively, you can you can enter the Front-channel logout URL in the following format: https://my-dashboard.com/auth/realms/gv/protocol/openid-connect/logout.

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

Required for Synergy Settings

Setting up a default Agent user

This step is important and required for the agent to work correctly. This user is only used internally by agents on endpoints to authenticate with the server. This user cannot be used to log in to the dashboard. For dashboard login, you must create your user in the gv realm.

1. Make sure it’s still the gv realm selected in the top left, not master.

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

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

1. 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].

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

Optional Settings

Completing the Agent Client Configuration

This step is optional if Synergy is being used and not required if Focus is being used.

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

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

1. 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.

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

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

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

1. 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.

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

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

2. 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.

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

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

1. (Optional) Click on the Accordion option Sync Settings in order to set up automatic synchronization of users from the LDAP Active Directory to Keycloak. It is also possible configure the auto-synchronization settings here

1. 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, the users need to be synchronized 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.

Creating a user to access the GetVisibility dashboard

By default, there are no users in the gv realm, meaning that nobody can access the dashboard to view agent activity, use analytics, run scans or create reports.

Users must either be created manually as described below, or imported, e.g. via LDAP user federation.

Users created in the gv realm will have full administrative access to the GetVisibility web console.

RBAC implementation for granular management of dashboard user permissions is on our roadmap.

1. Make sure that it’s still the gv realm selected in the top left, not master:

   

2. Click on the Users menu item on the left-side menu, this should load the (empty) Users list.

1. Click the Add user button at the top to open the Add user screen.

   
2. There is only one mandatory field here; The Username field should contain your desired username, e.g. admin.

1. Click Create. This will then load the User Details page for the user that was just created.

2. Here, click Set password.

1. Next, choose a strong password for the user. Leave the “Temporary” option on if the user should change their password on the first login.

1. Click Save.

2. Navigate to the /ui endpoint of the IP of the server or the domain if you configured any. E.g. https://my-dashboard.com/ui or https://10.10.121.127/ui

GetVisibility login page.

Confirm that the credentials are working as expected.

---

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 any additional assistance is required or the problem is not easily resolved by troubleshooting Network communications and authentication details, please reach out to Support following the steps here.