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.

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.


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.

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



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.


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.


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


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.



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