Introduction

Keycloak is an open source identity and access management tool. You can use Keycloak to secure supported applications like Omniscope. You can find out more about Keycloak by visiting their webpage.

Keycloak supports single-sign on, which allows you to avoid having to configure separate login credentials for users inside each application; instead you configure your users inside Keycloak, and allow your applications to communicate with Keycloak to login and retrieve a users identity.

Keycloak provides a lot of different security features and deployment options. This document is not intended to be an in-depth discussion of all these features. Instead we will guide you through the process of setting up Keycloak on your local PC and configuring Omniscope to use Keycloak to manage user authentication using OpenID Connect. Before deploying any access management tool on your production server you should ensure you are familiar with the technologies involved and have studied the providers documentation carefully.

Keycloak setup

Prerequisites

We will be installing and configuring Keycloak on our local computer.

Before you start make sure you have OpenJDK 1.8 or newer installed. You can download it here.

Installation

Download the latest version of Keycloak from here.

After downloading, extract the contents of the ZIP file to a local folder. You should see the following sub-folders:

• bin/
• domain/
• modules/
• standalone/
• standalone/deployments

Start Keycloak

Open a terminal window and navigate to the Keycloak folder and enter the following command:

Windows:

bin/standalone.bat

Linux:

bin/standalone.sh

Mac:

bin/standalone.sh

Setup the admin user

The first thing we need to do after starting Keycloak for the first time is to create our admin user.

In a browser, open http://localhost:8080/auth.

You should see a webpage asking us to enter our admin username and password. Enter your credentials and click CREATE. Now we can login to the Keycloak admin console. Navigate to http://localhost:8080/auth/admin/master/console/ and enter your admin credentials, then click Login.

Create a realm

A realm in Keycloak is used to isolate groups of applications and users. When we setup Keycloak for the first time it is configured with a single master realm. The master realm is reserved for administering Keycloak, so we need to create and configure a new realm for our own applications.

In the Keycloak admin console:

Click on Master in the top-left corner.

Click Add realm and enter a name. In this example i'm using the name visokio, but feel free to user whatever name you like. 

Click Create.

You should now see your realm listed in the top-left corner. You can click on the realm name to switch between the master realm or any other realms you have created.

Create a user

We now need to create one or more users for this realm. We will create a single user, but you can create as many users as you like.

In the Keycloak admin console ensure your new realm is selected, then:

Click Users.

Click Add user.

Enter a username and email address for the user. 

Set Email verified to ON.

Click Save.

Now we need to set a password for our new user:

Click Credentials.

Enter a password.

Untick Temporary. This will prevent the user having to change the password when they first login.

Click Set Password.

Now lets test logging into Keycloak with our new user.

Navigate to http://localhost:8080/auth/realms/visokio/account.

Enter the email address and password of our new user. We should see a confirmation message that login was successful.

Create a client

A Keycloak client manages the authentication of your users from your external application.

Navigate back to the admin console http://localhost:8080/auth/admin/master/console/ then:

Click Clients.

Click Create.

Enter a Client ID. In this example i'm using testclient.

Click Client protocol and select openid-connect.

Click Save.

Now we need to setup the client authentication and obtain our Client ID and Client Secret:

Click on the Settings tab.

Click Access type and change the value to Confidential.

Set the Valid Redirect URIs to: http://localhost/oidc-cb.

In case you intend to run Omniscope server on a port different from port 80 used in this example you need to use the same port number here, e.g. use http://localhost:8181/oidc-cb for port 8181.

You might also need to add http://localhost/oidc-locb here if you are going to use Logout method - Provider later while configuring Keycloak connection in Omniscope.

Click Save.

Now we need to make a note of our Client ID and Client Secret so we can configure this later on in Omniscope. The Client ID should already be visible in the Settings tab. You can obtain the Client Secret by clicking on the Credentials tab.

We've now finished our initial Keycloak setup! The next step is to configure Omniscope to authenticate using Keycloak.

Omniscope setup

Prerequisites

We will be setting up Omniscope to authenticate users using Keycloak.

Make sure Omniscope is installed on your local computer and you are running Keycloak.

Make sure that you have the right HTTP port configured. 

It must be the same port you used for http://localhost/oidc-cb url above.

Please note that you are always logged in as an admin/root user when you open locally installed Omniscope server in the browser by http://127.0.0.1:24679/ url or open Omniscope window from the system tray icon.

Use http://localhost (with the right port number configured above if it is different) if you need to log in as a different user.

Setup the Keycloak Provider

Start Omniscope. Click on the admin user button in the top-right corner and click Edit permissions.

Inside the Edit permissions dialog:

Scroll down to the OpenID Connect section and tick Set configuration for OpenID connect.

Click Add Provider. In the dropdown select Keycloak.

You should see the Keycloak provider has now been added, but is not yet configured.

Click Keycloak to open the Keycloak configuration dialog.

Enter the Issuer URI. The URI should be the form: http://localhost:8080/auth/realms/[Realm name]/, for example http://localhost:8080/auth/realms/visokio/.

Enter the Client ID and Client Secret you obtained earlier.

For more details regarding other options in the dialog see here.

Click Test Connection to ensure Keycloak has been successfully configured. You should see a popup informing you that validation was successful.

Choose Logout mode - Provider if you want users to log out of Keycloak when they log out of Omniscope session.

Now click Back then Save.

Create a Group

We now need to create a group of users that we allow access to Omniscope. These users will be authenticated using Keycloak.

Click on the admin user button in the top-right corner and select Edit permissions. In the Edit permissions dialog:

Scroll down to the Groups section and click Add Group.

Click on the Group name. In the Group permissions dialog:

Click Configure permissions and select the permissions for our users. In this example I am selecting Yes to all, but feel free to configure whichever permissions are required.

Click Add authentication mechanism and select OpenID Connect.

Now click OpenID Connect to configure our users. In the dialog:

Tick Restrict by email address.

Click the + button and add the email address of the user we added earlier in Keycloak.

Click Back, Back then Save.

Configure anonymous permissions

You will also need to restrict access to your Omniscope server for users that are not logged in. 

You can do it by opening Configure Anonymous Permissions on Edit Permissions dialog.

If you want to restrict any anonymous access to your files then click No To All then close the drop-down and click Save.

Testing authentication

We have now configured Keycloak as our OpenID authentication provider in Omniscope. The next step is to test and verify that the authentication process works as expected.

Before we can do this we must ensure that Omniscope is running as an external web server:

Open the admin page and click Network.

Tick Run external web server. 

Click Save Changes, then shutdown and restart Omniscoipe.

Now open a new Browser and navigate to the external webserver address (if you have set this up locally use http://localhost). You should see a login button in the top-right.

Click Login then click Continue with Keycloak. Omniscope will redirect your authentication request to the Keycloak server. You should now see a Log In window.

Enter the username and password of your user, then click Log In. If the authentication was successful you should now be redirected back to Omniscope. 

You have now logged in and are free to use Omniscope based on the permissions configured earlier. If you click on the user button in the top right corner you should see the users email address.

Custom scopes

One of the features of Keycloak is the ability to define Roles, and you can then use Restrict by claims configuration in the per-group folder configuration in Omniscope to automatically set permissions based on their role in Keycloak. 

Here is a brief summary and steps you can follow to define roles in Keycloak and then subsequently configuring Omniscope to use this to define permissions 

To create roles within Keycloak login into the server and go to Roles section from the sidebar navigation. You would need to use the administrator account of Keycloak server to perform these actions.

In the user configuration make sure that Role mappings have been correctly defined i.e. you assign the correct role to the correct user.

You may also need to ensure in the Client scopes section roles have been defined with the mappers section correctly configured.

Inside the folder configuration where you define keycloak configuration, you need to add roles to the custom scopes. This would allow Omniscope to query for the additional roles within keycloak hence its important you do this.

Please let us know if you have any questions or feedback.