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.

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

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

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

Choose "Group Membership".

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

Now, it is time to declare a Client.

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

Set discovery Urls in your Client Settings.

Add the previous Client Scope to your new client.

And set it to "Default".

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

Create groups for your users and create your first user.

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

Log in with your account:

And enjoy:

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'

Xavier Marin

Senior Software Engineer