Configuring Entitlements - BETA

This page lists entitlements configuration options for a user or service account with the administrator role.

Note

When users are referenced here, these can be either standard users or service accounts. For details about the security terminology used, refer to the Terminology section of the Authentication page.

Entitlement fields

The following table describes the fields present in the returned JSON files:

Name

Details

id

GUID for the package. You can use kxi pm list to find the id of the package. This value cannot be changed once it has been defined as it is required for future updates. This value can have multiple entity types associated with it.

internalId

GUID to uniquely identify the package and entity type combination. This value is automatically generated and used by the system.

entity

Name of the package with which the entitlement is associated.

entityType

Either database or package.

groups

One or more groups of users that are entitled to the entity. The information includes the group GUID provided by Keycloak, access levels and any row policies associated with specific tables.

owner

Name and GUID provided by Keycloak for the user who is the owner of the entity.

users

One or more GUIDs provided by Keycloak for the users that are in the groups associated with the entity.

policiesEnabled

Boolean used to determine if policies are enabled on the entity

policyTypes

List of policy types enabled currently row is the only supported type

These are the available entity types:

entityType

Description

database

Used to determine which groups of users can query a database

package

Used to determine which groups of users can view and edit package configuration and deploy a specific package

Define entitlements

Once the prerequisites are complete, entitlements are enabled and your groups are defined, you are ready to entitle groups of users to access specific packages, query data in specific databases and query specific rows of data in those databases.

View groups

First, list the available groups by calling the following:

bash

Copy 
kxi entitlement actors

console

Copy 
╭──────────────────────────────────────┬──────────────┬────────────────────────┬────────────╮
│ actor                                │ path         │ members                │ admingroup │
├──────────────────────────────────────┼──────────────┼────────────────────────┼────────────┤
│ marketing                            │ /marketing   │ name            access │ False      │
│ ------------------------------------ │              │ ------------    ------ │            │
│ ae3a8d5c-0afe-4fba-bbaf-dd962a76ad4a │              │ marketinguser1  RWX    │            │
│                                      │              │ marketinguser2  RWX    │            │
├──────────────────────────────────────┼──────────────┼────────────────────────┼────────────┤
│ research                             │ /research    │ name            access │ False      │
│ ------------------------------------ │              │ ------------    ------ │            │
│ cf16d416-3b6f-423d-b179-561251b98644 │              │ researchuser1   RWX    │            │
╰──────────────────────────────────────┴──────────────┴────────────────────────┴────────────╯

Note

If no groups are returned, you need to add one or more groups to Keycloak by following the instructions on Adding users to groups in the prerequisites guide.

The values returned are as follows:

Name

Details

actor

Group name and GUID provided by Keycloak for the group.

path

Path to group indicating subgroup structure.

members

List of users in the group including their id, name and access levels.

admingroup

True or False depending on whether this is an admin group.

Tip

Make a note of the group IDs as they are needed when updating the entitlements.

Create an entitlement

When you create a package (containing a database, pipeline and/or view) using the web interface or the CLI, the entitlement records are created for you.

You can view details of all entitlements or a single entitlement using the package id returned from kxi pm list.

Note

If you are deploying an assembly using the deprecated kxi assembly command rather than a package, you need to create the entitlement record yourself, following this guide:

Once you know the IDs of the groups, you can create an entitlement that allows users in those groups to query the database.

To create an entitlement, call the following:

bash

Copy 
kxi entitlement create <ID> <NAME> <TYPE> --groups <GROUPID1>:<ACCESS1>,<GROUPID2>:<ACCESS2>

The values specified are as follows:

Values

Details

ID

GUID for the package. Use kxi pm list to find the id of the package.

NAME

Name of the package.

TYPE

Currently only database and package are supported in the TYPE field.

GROUPID1,GROUPID2

List of GUIDs for the groups that are entitled to access this entity.

ACCESS1,ACCESS2

Access levels for the groups, used by package entitlements to determine access levels available.

Access levels

Access levels are used in package entitlements to determine what level of access users have to a package.

Warning

Only the Read Access applies for data entitlements.

The permissible values are any combination of the following:

Access

Details

R

Read access

W

Write access

X

Execute access

A

All access

Policies

Policies are used as part of row level entitlements to provide more granular data access.

Warning

Policies do not apply to package entitlements.

Currently, the only policy type available is row.

View entitlements

View all entitlements

Run the following command to view all entitlements:

bash

Copy 
kxi entitlement list

Below is an example of the returned value from the kxi entitlement list command:

bash

Copy 
╭──────────────────────────────────┬──────────┬────────┬─────────────────────────────────────────────────────┬─────────────────┬──────────┬─────────────────╮
│ entity                           │ entity   │ owner  │ groups                                              │ users           │ policies │ policy types    │
│                                  │ type     │        │                                                     │                 │ enabled  │                 │
├──────────────────────────────────┼──────────┼────────┼─────────────────────────────────────────────────────┼─────────────────┼──────────┼─────────────────┤
│ insights-demo                    │ database │ OWNER  │ id                                access  policies  │ name    access  │ False    │ name   enabled  │
│ -------------------------------- │          │        │ --------------------------------  -----   -------   │ ------  ------- │          │ -----  -------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │        │ YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYY   R                │ owner   ARWX    │          │ row    False    │
│                                  │          │        │                                                     │ user1   R       │          │                 │
│                                  │          │        │                                                     │ user2   R       │          │                 │
├──────────────────────────────────┼──────────┼────────┼─────────────────────────────────────────────────────┼─────────────────┼──────────┼─────────────────┤
│ insights-demo                    │ package  │ OWNER  │ id                                access  policies  │ name    access  │ False    │ name   enabled  │
│ -------------------------------- │          │        │ --------------------------------  -----   -------   │ ------  ------- │          │ -----  -------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │        │ ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZ   R                │ owner   ARWX    │          │ row    False    │
│                                  │          │        │                                                     │ user3   R       │          │                 │
╰──────────────────────────────────┴──────────┴────────┴─────────────────────────────────────────────────────┴─────────────────┴──────────┴─────────────────╯

View a specific entitlement

You can view details for a specific entity using the following command:

bash

Copy 
kxi entitlement get <ID> database

Below is an example of the returned value from the kxi entitlement get <ID> database command:

bash

Copy 
╭──────────────────────────────────┬──────────┬────────┬─────────────────────────────────────────────────────┬─────────────────┬──────────┬─────────────────╮
│ entity                           │ entity   │ owner  │ groups                                              │ users           │ policies │ policy types    │
│                                  │ type     │        │                                                     │                 │ enabled  │                 │
├──────────────────────────────────┼──────────┼────────┼─────────────────────────────────────────────────────┼─────────────────┼──────────┼─────────────────┤
│ insights-demo                    │ package  │ OWNER  │ id                                access  policies  │ name    access  │ False    │ name   enabled  │
│ -------------------------------- │          │        │ --------------------------------  -----   -------   │ ------  ------- │          │ -----  -------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │        │ ZZZZZZZZ-ZZZZ-ZZZZ-ZZZZ-ZZZZZZZZ   RW               │ owner   ARWX    │          │ row    False    │
│                                  │          │        │                                                     │ user3   RW      │          │                 │
╰──────────────────────────────────┴──────────┴────────┴─────────────────────────────────────────────────────┴─────────────────┴──────────┴─────────────────╯

View the entitlements you own

Run the following command to view the entitlements you own:

bash

Copy 
kxi entitlement list --own

Update data entitlements

To update the list of users entitled to a package, use one of the following methods:

  • Keycloak: a Keycloak administrator can add or remove users from a group that is already entitled to access the package.

  • Entitlements: you can edit entitlements using the following commands:

    • kxi entitlement manage - uses an interactive session to edit data and package entitlements.

      Note

      Limitations:

      • The Maintainer role allows you to modify only the entitlements you own. The manage command displays only the entitlements that you own and therefore can modify.

      • The manage command does not currently support the management of row level entitlement policies.

    • kxi entitlement update - allows you to change:

      • owner - updates the owner of the entity.

      • groups - replaces the list of groups with the list provided.

      • entity name - updates the name of the entity.

      • access - updates Read, Write, Execute and Admin access levels, used by package entitlements.

        Warning

        The entity name value must match the package name. If you rename the package in the Web Interface or the CLI the entity name is updated, but if there is ever a mismatch you can use kxi entitlement update <ID> <TYPE>--name <NAME> to update the entity name. Only users with the insights.entitlements.admin can query data from packages with a mismatched name.

        Refer to the Roles documentation for more details.

    • kxi entitlement add-groups - adds one or more groups to the current list of groups.

    • kxi entitlement rm-groups- removes one or more groups from the current list of groups.

Follow the quickstart guide for an example of how to create a group, add users to that group, and entitle that group to query data.

Update row level entitlements

When you need to update the policy settings, including enabling and disabling policies and the list of policies assigned to a table and group of users, you can take one of the following actions:

  • kxi entitlement policies-enable- enables the use of policies on a database.

  • kxi entitlement policies-disable - disables the use of policies on a database.

  • kxi entitlement policy-mapping - enables and disables specific types of policy and edits the list of policies associated with a table and group of users.

Follow the row level entitlements guide for an example of how to add row policies to a specific database to allow a group of users access to all rows or a subset of rows.

Change synchronization

It takes a short period of time for changes to entitlements to synchronize across the system. Existing queries or new queries during that sync window honor the previous set of entitlements. This should generally take no longer than a minute.

For example, if you create or update an entitlement and immediately issue a query, kdb Insights Enterprise obeys the previous entitlement state until the changes are synchronized across the system.