Skip to content

User Authentication and Authorization

The page outlines how kdb Insights Enterprise uses Keycloak to authenticate users and service accounts across its interfaces.

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

This page builds on the information found on the Keycloak and PostgreSQL configuration page.

Administration console

Keycloak is configured through the administration console.

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

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

kubectl get statefulset <$RELEASE_NAME>-keycloak -o jsonpath='{.spec.template.spec.containers[*].env[?(@.name=="KEYCLOAK_ADMIN")].value}'

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. The cnpg-database will migrate these secrets on install into superuser-secret(postgres-password) and bn-keycloak-secret(keycloak administrator).

Terminology

Here are some core terms to help you understand how kdb Insights Enterprise uses Keycloak.
Term Details
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.
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.
groups Groups manage groups of users and service accounts. Click here to see how to manage groups.
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.
roles Roles define a type of user. kdb Insights Enterprise assigns permissions to specific roles that can then be assigned to users.
service accounts Service accounts are associated with clients and allow roles and permissions to be assigned to clients for authorization. Click here to see how to manage service accounts.
users Users are individuals that can log into kdb Insights Enterprise. Click here to see how to manage users.

For additional definitions see 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 kdb Insights Enterprise 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

Users and service accounts

Details on how to manage the users and service accounts are listed below:

Roles and entitlements

A role defines the operations a user is allowed to perform within the system. For example, a user with the Viewer role can query data but cannot tear down a database.

An entitlement, when enforced, limits the user's access to specific entities (packages or data). For example, a user with a Read entitlement to a single package can only view that package in the web interface and through the CLI.

Roles

kdb Insights Enterprise comes with a selection of preconfigured high level roles, as they are defined in the table below:

Name Role Details
Views-only insights.role.viewer.dashboard Provides read-only access to Views the user is entitled to. No access/visibility to other entities such as databases, tables, pipelines, packages, or queries.
Viewer insights.role.viewer Extends Views-only access to include all entitled entities (databases, packages, pipelines, views) and logs. Does not allow deploying, updating or deleting entities and logs. This role cannot export configuration or modify the logging level.
Reporter insights.role.reporter Extends the Viewer role with the ability to modify log levels and export configuration. Also allows custom queries on the kdb Insights database.
Developer insights.role.developer Extends the Reporter role with the ability to deploy and tear down resources. Can create pipelines, databases, and views, and develop streaming applications, but cannot delete persisted data.
Maintainer insights.role.maintainer Extends the Developer role with the ability to delete persisted data within the system.
Administrator insights.role.administrator Includes all permissions; the user can view and edit all entitlements and is not subject to entitlements enforcement.
Entitlements Administrator insights.entitlements.admin Enables viewing and editing of all entitlements but does not grant access to system entities.

The grid below shows an overview of the capabilities per role:

Capacity to Manage Views-only Viewer Reporter Developer Maintainer Administrator Entitlements Admin
Display views Y Y Y Y Y Y
View other package entities Y Y Y Y Y
Query and stream data Y Y Y Y Y
View logs/diagnostics Y Y Y Y Y
Use the scratchpad Y Y Y Y Y
Create package entities Y Y Y
Update package entities Y Y Y
Start/stop package entities Y Y Y
View entitlements Y Y Y Y Y Y
Create/Update entitlements Y Y Y Y
Delete package entities Y Y
View auditing Y Y
All accessing Y

Note

Users who are not Administrators or Entitlements Administrators can only view entitlements for packages they are entitled to.

Expand for examples

  • To give a user read-only access to a specific package:

    • Assign the insights.role.viewer role.
    • Grant a READ entitlement for the package. A WRITE entitlement alone does not allow modifications if the user's role does not permit it.

  • To allow a user to edit a package:

    • Assign the insights.role.developer role.
    • Grant a WRITE entitlement for the package.

  • To allow a user to create their own packages while having entitlements enforced on other packages:

    • Assign the insights.role.maintainer role.
    • Grant WRITE entitlements for any existing packages they need to interact with.

  • To grant full administrative access:

    • Assign the insights.role.administrator role. This role has full access and does not require additional entitlements.

Access model example

The following example demonstrates a typical configuration where multiple users are assigned different roles and entitlements based on their responsibilities within kdb Insights Enterprise.

Entitlements

Entitlement Type Description
demo-ro package Read-only access to the demo package
demo-rw package Read/Write access to the demo package
demo-data database Query Access to the demo database

Users

User Role Entitlements
Business User insights.role.viewer demo-ro, demo-data
Developer insights.role.developer demo-ro, demo-data
Maintainer insights.role.maintainer demo-rw, demo-data
Entitlements Admin insights.entitlements.admin *
Administrator insights.role.admin *
Business User
  • Can log in to the user interface or use the CLI to view running (or not running) demo package he has read entitlements to
  • Can see the pipelines; databases and views within the demo package
  • Can view the entitlements to his package
  • Cannot make any changes to any entities
  • Cannot delete any packages
  • Cannot start or stop any packages
  • Cannot create his own packages or any entities of any type
  • Cannot create ot edit any entitlements
  • Cannot view entitlements to any other package
Developer

Limited Access:

  • Can login to the user interface or use the CLI to view running (or not running) demo package he has read entitlements to
  • Can see the pipelines; databases and views within the demo package
  • Can view his entitlements
  • Cannot make any changes to the demo package
  • Cannot edit entitlements to the demo package
  • Cannot delete the demo package
  • Can start or stop the demo package
  • Can create his own package and deploy it
  • Can view and edit the entitlements to his package
  • Cannot create, edit or view entitlements to any other package
Maintainer

Full Access to entitled entities:

  • Can log in to the user interface or use the CLI to view running (or not running) demo package he has read entitlements to
  • Can see the pipelines; databases and views within the demo package
  • Can make changes to the demo package
  • Can edit entitlements to the demo package
  • Can delete the demo package
  • Can start or stop the demo package
  • Can edit entitlements to the demo package
  • Can create his own package and deploy it
  • Can manage the entitlements to his package
  • Cannot create, edit or view entitlements to any other package
Administrator

Full Access to all entities:

  • Can log in to the user interface or use the CLI to view running (or not running) demo package he has read entitlements to
  • Can see all pipelines; databases and views
  • Can make any changes to any package
  • Can delete any package
  • Can start or stop any package
  • Can create his own package and deploy it
  • Can create; edit or view entitlements to any package
  • ACan create his own package and deploy it
Entitlements Admin

Full access to entitlements; no access to entities:

  • Can log in to the user interface or use the CLI to view running (or not running) demo package he has read entitlements to
  • Can see the pipelines; databases and views within the demo package
  • Cannot make any changes to any package
  • Cannot delete any package
  • Cannot start or stop any package
  • Cannot create his own package and deploy it
  • Can create, edit or view entitlements to any package
  • Cannot create his own package and deploy it

Configuring the realm

Configuring email

Keycloak sends emails to users to verify their email addresses and when they forget their passwords. To enable Keycloak to send emails, you need to provide Keycloak with your SMTP server settings.

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.