Keycloak

Keycloak is a suite to interface with various identity providers like Active Directory, LDAP or SAML. It sits between VDG Sense and the Identity provider to provide VDG Sense with access to Active Directory. More information can be found on thehttp://keycloak.org website.

Installation

Keycloak can be downloaded from the keycloak website. It is recommended to install it on the VDG Sense management server so that keycloak can be configured to block any remote connections. This means the configuration webpage can only be accesed from the local PC.

In case of using Keycloak with Failover functionality it is recommended to install it on the Failover server.

Follow this procedure to install keycloak:

  1. Download Keycloak 15.0 from https://www.keycloak.org//downloads.html It is the ‘Distribution powered by WildFly’ zip file.

  2. Download OpenJDK 15 here: https://jdk.java.net/archive/

  3. Extract content of zip file to C:\OpenJDK or other preferred location

  4. Assuming it is extracted in C:\OpenJDK add following item to system variables:

  5.  

     

  6. Unzip ‘keycloak-15.0.2.zip’ or newer version in ‘C:\Program Files\VDG Security\Sense’ folder

  7. Copy folder C:\Program Files\VDG Security\Sense\keycloak-14.0.2\docs\contrib\scripts\service to C:\Program Files\VDG Security\Sense\keycloak-15.0.2\bin

  8. As administrator CMD run: keycloak/bin/service/service.bat install

  9. Go to 'computer management'->services

  10. Enable automatic start for service Wildfly, this is the keycloak windows service provider

  11. Start Wildfly service

Failover

If installed on Failover server or separate server, remote access needs to be enabled to Keycloak service. To this open following file:

C:\Program Files\VDG Security\Sense\Software\keycloak-15.0.2\standalone\configuration\standalone.xml

Lookup following <interfaces> tag and change accordingly:

1 2 3 4 5 6 7 8 9 </profile> <interfaces> <interface name="management"> <any-address/> </interface> <interface name="public"> <any-address/> </interface> </interfaces>

Restart Wildfly service after changing this file to enable remote connection

More information can be found here: http://docs.wildfly.org/23/Admin_Guide.html#Interfaces_and_ports

Configuration

Assuming Keycloak is up and running. Open http://127.0.0.1:8080/auth/.

Keycloak will ask for the admin username and password as this has not been configured. Configure a safe and hard to guess password.

After this user has been created you will be directed to the login page.

Add a realm

Keycloak can be setup to be used by more then one software integration. For each software integration a realm should be setup.

So setup a realm for Sense.

  • Hover with the mouse over 'Master' in the top-left corner of the screen.

  • Select 'Add realm' from the popup

  • Use 'Sense' as realm name

 

Add a client

The Sense Videomanager needs to request the users from Keycloak. So SenseVideoManager needs to be able to authenticate itself, this is done with a client-grant. The client-grant has to be setup in Keycloak.

  • Select the ‘Sense’ Realm

  • Select 'Clients' in the menu on the left-side

  • Click the 'Create'-button on the right-side above the list.

  • Use the following:

    • Client ID: 'sense-client-credentials'

    • Client Protocol: 'openid-connect'

    • Root URL: leave empty

  • If the added item is not yet selected, select the 'Sense-client-credentials' from the list and set it with following settings:

    • Access Type: confidential

    • Service Accounts Enabled: ON

    • Authorization Enabled: ON

    • Valid Redirect URL: /*

  • Press ‘Save’ button

The Credentials tab shows the login credentials which need to be used in Sense.

The Client ID (sense-client-credentials) and Client Secret (83089eda-ac37-45e0-aa17-a8f1a2cddfdc) are needed later in the Identity Provider dialog in Sense. You should be able to copy these values from Keycloak. They are unique for each installation.

The client-grant requires access to the users. The video manager only queries the users, it does not add or modify users.

  • Select the tab 'Service Account Roles'

  • From the ‘Client Roles'-dropdown select 'realm-management’.

  • From the 'Available Roles’-list add: ‘query-clients', ‘manage-users’ and ‘view-users’

 

Active Directory

Add a user provider to Keycloak

  • Select 'User Federation' from the menu on the left-side

  • From the ‘Add provider'-dropdown select 'ldap’

  • The field ‘Username LDAP attribute’ should be set to sAMAccountName.

  • Setup depending on the Active Directory settings on site

To correctly import the username in the keycloak userlist the following change has to be made in the ‘Mappers’ section:

Click ‘username’ and change the ‘LDAP Attribute’ value from ‘cn’ to 'sAMAccountName':

 

  • Go back to ‘Settings’ menu

  • Test the connection to your AD-server

  • Test the authentication to your AD-server

  • If all tests are okay, the user can be synchronized manually:

If required Keycloak can automatically sync new users from Active Directory. Open ‘Sync Settings’ for this:

In this case changed it is checked every 60 seconds.

Check the users

All synchronized users can be viewed after the active directory settings are configured.

  • Select 'Users' from the menu on the left-side

  • Click the 'View all users'-button

    • The result should be a list of all AD-users and the native 'Keycloak'-users.

  • The users from AD have a field 'Federation link':