Secure Discovery Explorer with KeyCloak

Secure your Discovery Explorer by authoring access rules for your dashboards with KeyCloak.

Secure Discovery Explorer with KeyCloak

Discovery Explorer is a great tool if you want to expose your Discovery dashboards easily.

Since 1.0.38, you can plug it with KeyCloak. It is an Open Source Identity and Access Management which provides user federation, strong authentication, user management, fine-grained authorization, and more. It allows you to quickly setup an identity manager, or, use it as a proxy for your own identity manager (LDAP/SAML/Google/etc…).

Through this blog post, we will show you how to perform a basic setup.

KeyCloak quick setup

First, you have to install KeyCloak. The easiest way is to use Docker.

$ docker run -p 9012:8080 \
   -v /opt/keycloak/data:/opt/keycloak/data \
   -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=strongAdminPasswd \
   quay.io/keycloak/keycloak:latest start-dev

Once started, you can login with the admin account on http://localhost:9012/admin/.

The first thing to do is to create a new realm.

KeyCloak Realm creation
Realm creation

Call it, let say, "senx" (or whatever you want).

KeyCloak Realm setting
Realm setting

Then, create a Client Scope in order to manage KeyCloak groups in Discovery Explorer.

KeyCloak Client Scope creation
Client Scope creation

Add a new custom mapper to your brand-new Client Scope.

KeyCloak mapper
Mapper

Choose "Group Membership".

KeyCloak predefined mapper
Predefined mapper

And set its name to "groups" (this name is important for Discovery Explorer)

KeyCloak Mapper settings
Mapper settings

Now, it is time to declare a Client.

KeyCloak Client creation
Client creation

Set the Client ID to "discovery" (or whatever you want).

KeyCloak Client settings
Client settings

Set discovery Urls in your Client Settings.

KeyCloak Client settings

Add the previous Client Scope to your new client.

KeyCloak Client Scope settings
Client Scope settings
KeyCloak Client Scope settings
Client Scope settings

And set it to "Default".

KeyCloak Client Scope settings
Client Scope settings

You are almost ready.

You need to grab the public RSA256 key (copy it somewhere) in order to allow the Discovery Explorer back-end to decode the JWT token (provided by the front-end through HTTP headers).

KeyCloak public key
Public key

Create groups for your users and create your first user.

KeyCloak User creation
User creation

Then attach the new user to the desired group.

Set a password in the "Credential" tab.

Discovery setup

First, create a configuration file in /opt/discovery (or a directory of your choice).

{
  "dashRoot": "/data",
  "plugins": [],
  "security": {
    "keycloak": {
      "baseUrl": "http://localhost:9090",
      "keycloakBaseUrl": "http://localhost:9012",
      "keycloakRealm": "senx",
      "keycloakClient": "discovery",
      "rsaPublicKey": "MIcxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1EcQIDAQAB"
    },
    "routing": [
      {
        "path": "/.*",
        "groups": [ "/SenX" ],
        "private": true
      },
      {
        "path": "/senx/demo/*",
        "groups": [],
        "private": false
      },
      {
        "path": "/secret_project/.*",
        "groups": [],
        "private": true,
        "user": "miles.dyson@sky.net"
      }
    ]
  }
}

Entries explanation:

  • dashRoot: Mandatory, the root path where your dashboards are located. Because you run it into a Docker container, it must be /data
  • plugins: List of Discovery plugins. It will be the subject of a future post.
  • security: The KeyCloak and access configuration
    • Keycloak: The KeyCloak configuration
      • baseUrl: Mandatory, the base URL of your Discovery Explorer
      • keycloakBaseUrl: Mandatory, your KeyCloak URL
      • keycloakRealm: Mandatory, the dedicated Realm you have previously created
      • keycloakClient: Mandatory, the Client ID you have previously created
      • rsaPublicKey: The RSA256 public key associated with your realm
    • routing: Mandatory, your access rules
      • path: Mandatory, the regular expression corresponding to the path associated with this rule
      • groups: A mandatory list of groups to which a user must belong in order to allow access to this path. An empty list indicates that a user has just to be authenticated.
      • private: Mandatory, it indicates whether a user must be at least authenticated to access this path. Set it to false and a user doesn't have to be authenticated to access it.
      • user: Optional, unique user name if you want to allow a specific user to access this path

In this sample:

  • { "path": "/.*", "groups": [ "/SenX" ], "private": true }:
    a user must be authenticated and must belong to the SenX group.
  • { "path": "/senx/demo/*", "groups": [], "private": false }:
    overrides the previous rule, dashboards located in /senx/demo (and sub folders) are publicly available.
  • { "path": "/secret_project/.*", "groups": [], "private": true, "user": "miles.dyson@sky.net" }:
    overrides previous rules, dashboards located in /secret_project (and sub folders) are only available for Miles.

Install Discovery with Docker:

$ docker run -p 9090:8080 \
   -v /opt/discovery/dashboards/:/data/ \
   -v /opt/discovery/conf.json:/opt/discovery-dashboard/conf.json \
   warp10io/discovery-explorer:1.0.38

Open your browser with: http://localhost:9090

Discovery Explorer menu
Discovery Explorer menu

Log in with your account:

Login screen

And enjoy:

Discovery menu
Discovery menu

Going further

You can customize the KeyCloak login screen, use more than one identity provider (you can see Google in a previous screenshot), and use WarpFleetSynchronizer to deploy your dashboards.

Here is a docker-compose to start quickly:

version: '2'
services:
  keycloak:
    image: 'quay.io/keycloak/keycloak:20.0.1'
    ports:
      - '9012:8080'
    command: 
      - start-dev 
    volumes:
      - '/opt/keycloak/data:/opt/keycloak/data'
    environment:
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=strongAdminPasswd
      
  discovery-explorer:
    image: 'warp10io/discovery-explorer:1.0.38'
    ports:
      - '9090:3000'
    volumes:
      - '/opt/discovery/dashboards/:/data/'
      - '/opt/discovery/conf.json:/opt/discovery-dashboard/conf.json'