Getvisibility Reseller Keycloak Manual Installation Guide

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 all of the configuration steps required (including the steps used to create the default Keycloak Realm configuration) for setting up the Keycloak environment correctly.

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

Logging into Keycloak admin panel

To log into Keycloak admin panel please access:

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

Replace my-reseller.net with IP or domain name of the product.

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

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

Configuring the Realm

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

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

Open

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

Configuring the Dashboard Client

A Client in Keycloak is used to encapsulate a Client authentication mechanism and configuration for a particular endpoint consumer (E.g. an API or a frontend)

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

Open

2. Click on the Create button in the top-right of the Clients list

3. When the Add Client screen opens, enter the following information:

   1. Client ID as dashboard

   2. Client Protocol as openid-connect (also known as OIDC)

   3. Root URL as the current host name in your URL (e.g. https://my-reseller.net as in the example above)

4. Once the client has been created, it will open the new dashboard client configuration Settings tab

Complete the following information:

1. (Optional) Name will be a human-readable identifier for the client. You can make this Dashboard

2. (Optional) Description will be a human-understandable description of the client’s purpose. You can make this Dashboard authentication client

3. Login Theme (not selected in the example image below) will be the theme created for your reseller (E.g. myreseller-theme) that you can select from the dropdown control

4. Client Protocol should be automatically selected as openid-connect from our initial creation of the client

5. Click/Set the Front Channel Logout to On, this will cause a new field to appear (Front-Channel Logout URL)

6. Enter the Front-Channel Logout URL using the following formula: {current host name}/auth/realms/gv/protocol/openid-connect/logout
   E.g. https://my-reseller.net/auth/realms/gv/protocol/openid-connect/logout

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

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

    

9. Click the Save button at the bottom of the screen then return to the Clients list

Configuring the Agent Client

A Client in Keycloak is used to encapsulate a Client authentication mechanism and configuration for a particular endpoint consumer (E.g. an API or a frontend)

1. Click on the Create button in the top-right of the Clients list

    

2. When the Add Client screen opens, enter the following information:

   1. Client ID as agent

   2. Client Protocol as openid-connect (also known as OIDC)

   3. Root URL as the current host name in your URL (e.g. https://my-reseller.net as in the example above)

    

3. Once the client has been created, it will open the new agent client configuration Settings tab
   Complete the following information:

   1. (Optional) Name will be a human-readable identifier for the client. You can make this Agent

   2. (Optional) Description will be a human-understandable description of the client’s purpose. You can make this Agent authentication client

   3. Client Protocol should be automatically selected as openid-connect from our initial creation of the client

   4. Update the Valid Redirect URIs to include any secure URL on the network. This is a required field and that is the only reason that it is needed.
      This field isn’t required for anything in particular for the agent client configuration.

       

4. Click the Save button at the bottom of the screen then return to the Clients list

(Required for Synergy) Setting up Agent authentication flow

Steps #1 Keycloak authentication flow

1. Go to Authentication → Flow.

2. Choose Direct Grant, press the copy button and specify some name (i.e. X509 Direct Grant).

3. Remove everything apart from Username Validation by selecting Actions -> Delete

4. Press Add execution and select X509/Validate Username from the dropdown, and then press save.

5. You should get a view the same as below.

6. Navigate to X509/Validate Username → Actions → Config.

Specify the name of the config.

Set User Identity Source to Subject's e-mail and User mapping method to Username or email.

Save it.

(Required for Synergy) Setting up a default Agent user

Steps #2 Keycloak client and user

This step is important and required 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 agent@gv.com:

    

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

(Required for Synergy) Setting up a default Agent user authentication

Steps #3 Keycloak client and user authentication

Go to Clients and select agent and choose Edit.

If agentdoes not exist, then press create, and specify Client ID as agent.

Go to the very bottom of the page to the Authentication Flow Overrides , then to Direct Grant Flow and set it to X509 Direct Grant. Save.

(Optional) Configuring the LDAP User Federation for Active Directory

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.

Now that we have created the Realm and Client, we need to now configure the actual LDAP Active Directory Authentication integration so that our Active Directory users may use their internal organization credentials to login to the Dashboard.

Creating the User Federation

Please follow these steps to configure the LDAP User Federation:

1. Click on the User Federation menu item on the left-side menu to access the User Federation configuration screen

    

2. Click on the Add provider… dropdown and select the item labelled ldap

    

3. Once ldap has been selected, it will open the Add user federation provider → Required Settings screen
   Complete the following information:

   1. Edit Mode should be READ_ONLY

   2. Vendor should be Active Directory

   3. Username LDAP attribute should be sAMAccountName

   4. Connection URL should be the accessible LDAP server address (E.g. ldap://127.0.0.1)

   5. Users DN should be the user location within the LDAP tree. This will follow a structure like DC=domain,DC=extension (E.g. DC=aws-domain,DC=com)

   6. Bind Type depends whether you want to only find users specified by Users DN (Option One Level) or whether to search the whole SubTree for Users (Option Subtree)

   7. Bind DN will be the username to use for the server access

   8. Bind Credential will be the password to use for the server access
      
      

4. 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 will need to use the Public IP address of the LDAP server.

    

5. Click on the button Test authentication to test the LDAP Server authentication details.
   If this step fails or hangs, it’s likely that the credentials are not correct. If the previous step (Step 4) succeeded then this step should also succeed if the LDAP server credentials are correct.

    

6. Click on the Accordion option Sync Settings in order to set up automatic synchronization of users from the LDAP Active Directory to Keycloak
   Completed the following items:

   1. Click/Set Periodic Full Sync to On
      You can also select Periodic Changed Users Sync if you only wish to process the Active Directory user change deltas instead of resynchronizing everything again

   2. Change the Full Sync Period to a value (in seconds) that is appropriate for the customer (Default is 604800 seconds which equals 7 days)

      
      
      

7. Click the Save button at the bottom of the screen, this will change the state of the screen and more buttons will appear 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

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 support@getvisibility.com