Skip to content

Authentication and authorization

Keycloak is an open-source identity and access management platform.

kdb Insights Enterprise uses Keycloak to provide features such as:

  • User authentication and authorization
  • Service account authentication and authorization
  • Role management
  • Single sign on (SSO) and identity brokering

Administration console

Keycloak is configured through the administration console.

You can access the Keycloak administration console at https://{INSIGHTS_HOSTNAME}/auth with the Keycloak administrator username and password.

The administrator username is defined in the Keycloak environment variables ConfigMap.

kubectl get configmap -l app.kubernetes.io/name=keycloak

The administrator password is defined in the kxi-keycloak secret.

kubectl get secret kxi-keycloak

Administration passwords

There are four passwords that are used to administer Keycloak, set during installation

Password Description
admin-password This is the password for the Keycloak administrator
management-password This is the password for the WildFly management user
postgres-password This is the password for the database superuser
password This is the password for the database user that Keycloak uses

These are stored in two secrets called kxi-keycloak and kxi-postgresql.

Terminology

Here are some core terms to help you understand how kdb Insights Enterprise uses Keycloak.

users

Users are individuals that can log into kdb Insights Enterprise.

authentication

Authentication is the act of verifying that a user is who they say they are.

authorization

Authorization determines what operations a user is allowed to perform.

roles

Roles define a type of user. kdb Insights Enterprise assigns permissions to specific roles that can then be assigned to users.

clients

Clients are entities that can request Keycloak to authenticate a user or can authenticate themselves with Keycloak. kdb Insights Enterprise is a client of Keycloak.

service accounts

Service accounts are associated with clients and allow roles and permissions to be assigned to clients for authorization.

identity provider

An identity provider is a service that can authenticate a user. Keycloak is an identity provider.

identity brokering

Identity brokering is the process of using a different identity provider to authenticate users instead of Keycloak.

realm

A realm manages a set of users, roles and clients. Users and clients belong to a realm. When a user logs in, they log into a realm. Realms are isolated from each other, allowing Keycloak to manage distinct groups of users and clients.

More definitions of Keycloak terms can be found at:

Keycloak Core Concepts and Terms

Realms

Keycloak is deployed as a dependency of kdb Insights Enterprise by default and the realm name is insights.

This realm contains all of the users, clients and roles.

To save resources, if you are deploying kdb Insights Enterprise multiple times in a cluster, you can use one shared Keycloak instance for all of the Insights deployments. In this case the realm name isinsights-<NAMESPACE>, where <NAMESPACE> is the Kubernetes namespace where Insights is deployed.

Read the shared Keycloak documentation for more information.

Set this variable to allow you to easily copy and paste any commands that reference it.

export REALM_NAME=insights

Roles

kdb Insights Enterprise comes with a selection of preconfigured high level roles, these are:

Name Role Details
Viewer insights.role.viewer This role allows a user to view existing reports, pipelines and queries but not deploy, update or delete them. This role can view logs but cannot modify the logging level of the platform. This role also cannot export any contents from the system other than diagnostics.
Reporter insights.role.reporter This role extends the viewer role with the ability to modify log levels and export configuration from the platform. This role can also perform custom queries on the Insights database.
Developer insights.role.developer This role adds the ability to deploy and teardown resources within Insights. This role can also create new pipelines, databases and reports. This role can develop streaming applications in Insights but is unable to delete any persisted data within the system.
Maintainer insights.role.maintainer This role has no restrictions and can perform all actions within Insights.

Beta features

New or experimental features are sometimes included in a release behind a beta flag. Beta features are an opt-in setting that are only visible to users that have the insights.builder.allowBeta role. This is also granted to all user profiles higher than insights.role.reporter. When this role is provided, a toggle is available in the Insights UI to enable these beta features. For the list of beta features in a given release, see the latest release notes.

Managing users

Creating users

  1. Log into the administration console.
  2. Choose REALM_NAME from the top-left realm drop-down
  3. Click Users in the menu.
  4. Click Add User.
  5. Enter the details for the new user.
  6. Click Save.

Warning

Changes made to the Master realm will be lost upon upgrade of kdb Insights Enterprise. Always add users to your REALM_NAME.

Use kxi user to create a new user.

kxi user create USERNAME \
    --email EMAIL \
    --password PASSWORD \
    --temporary

Replace the following:

  • USERNAME: Username for the new user.
  • EMAIL: Email for the new user.
  • PASSWORD: Password for the new user.

Note

The user will be asked to reset their password on first login when the --temporary flag is set

Assigning roles

Assign roles to a user through the Role Mappings tab for that user.

  1. Log into the administration console.
  2. Click Users in the menu.
  3. Click the user that you want to add the roles to.
  4. Click the Role mappings tab.
  5. Click Assign role.
  6. Select the role you want to assign to the user from the dialog.
  7. Click Assign.

Use kxi user to assign roles.

kxi user assign-roles USERNAME --roles ROLES

Replace the following:

  • USERNAME: Username to assign roles to.
  • ROLES: Comma-separated list of roles to assign.

Note

View available roles with kxi user get-available-roles

Password resets

You can reset passwords via the administration console.

  1. Log into the administration console.
  2. Click Users in the menu.
  3. Click the user whose password you want to reset.
  4. Click the Credentials tab.
  5. Enter a new password.
  6. Click Reset Password.

Use kxi user to reset a user's password.

kxi user reset-password USERNAME --password PASSWORD

Replace the following:

  • USERNAME: Username to reset password for.
  • PASSWORD: New password for the user.

This requires email to be configured for the realm.

To enable a 'Forgot password?' link on the login screen:

  1. Log into the administration console.
  2. Click Realm settings in the menu.
  3. Click the Login tab.
  4. Toggle Forgot password to ON.

A 'Forgot password?' link will now be displayed on the login screen.

Identity brokering

To use an identity provider other than Keycloak to authenticate users, configure this under Identity Providers in the menu.

The setup for this varies depending on the type of identity provider.

Read the Keycloak documentation for your specific use case.

Keycloak Identity Brokering

First login

A user that authenticates via a different identity provider than Keycloak must log in at least once before roles can be assigned to them.

Identity provider is not visible on the login screen

If an identity provider is configured but you can't see it on the login screen, ensure you are getting redirected to the correct login page: https://${INSIGHTS_HOSTNAME}/auth/admin/${REALM_NAME}/console/

Managing service accounts

Creating service accounts

To create a new service account in the administration console:

  1. Click Clients in the menu.
  2. Click Create client.
  3. Leave the client type as OpenID Connect.
  4. Enter a Client ID.
  5. Click Next.
  6. Toggle Client authentication to ON.
  7. Select Service account roles.
  8. Click Save.

Assigning roles

Assign roles to a service account through the Service accounts roles tab for that client.

  1. Log into the administration console.
  2. Click Clients in the menu.
  3. Click the client that you want to add the roles to.
  4. Click the Service accounts roles tab.
  5. Click Assign role.
  6. Select the role you want to assign from the dialog.
  7. Click Assign

Use kxi user to assign roles to a service account.

kxi user assign-roles service-account-CLIENT_ID --roles ROLES

Replace the following:

  • CLIENT_ID: Client that you want to add the roles to
  • ROLES: Comma-separated list of roles to assign

Note

View available roles with kxi user get-available-roles

Service account user names

Each client has an associated service account user named service-account-CLIENT_ID. The role needs to be assigned to this account.

Retrieving a secret

To retrieve the client secret for a service account in the administration console:

  1. Click Clients in the menu.
  2. Click the client that you want to retrieve the secret for.
  3. Click the Credentials tab.
  4. Click the Copy to clipboard button to copy the client secret.

Obtaining an access token

Use the client credentials flow to obtain an access token for a service account.

Here is an example of retrieving an access token using curl:

Variable Description
KC_CLIENT_ID Client ID for the service account
KC_CLIENT_SECRET Client secret for the service account 
export INSIGHTS_TOKEN=$(curl --header "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=$KC_CLIENT_ID&client_secret=$KC_CLIENT_SECRET" "https://${INSIGHTS_HOSTNAME}/auth/realms/${REALM_NAME}/protocol/openid-connect/token" | jq -r '.access_token')

Initial service account

You can create a service account when installing kdb Insights Enterprise. Set service account details in the install configuration file.

keycloak:
    initClient:
        # Enable the service account
        enabled: true
        # Name for the service account
        clientId: "test-publisher"
        # Secret for the service account
        clientSecret: "sp3cials3cr3t"

Read the configuration documentation for information.

Default clients

kdb Insights Enterprise comes with internal clients as part of the application. These are for system use and should not be updated by the user.

Client
account
account-console
admin-cli
broker
gui
kxi-operator
realm-management
security-admin-console

Configuring the realm

Configuring email

In the administration console:

  1. Click Realm settings in the menu.
  2. Click the Email tab.
  3. Enter the appropriate details.
  4. Click Save.

To configure email at installation time use the values detailed in the Keycloak configuration section.

Configuring authentication

Password policies

kdb Insights Enterprise supports a wide range of password policies.

Read the configuration documentation for information on the default password policy and how to adjust it at installation time.

To change the password policy in the administration console:

  1. Click Authentication in the menu.
  2. Click the Policies tab.
  3. Select the policy to add in the Add policy dropdown.
  4. Enter a value that applies to the chosen policy.
  5. Click Save.