Configuring Entitlements

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
entity	Name and UUID of the package with which the Entitlement is associated.
entity type	Either `database` or `package`.
owner	Name provided by Keycloak for the user who is the Entitlement owner
groups	One or more groups of users that are entitled to the entity. The information includes the group name provided by Keycloak, access levels and any row policies associated with specific tables.
users	One or more users that are in the groups associated with the entity and access types
policies enabled	`True` or `False`
policy types	List of the policy types currently enabled. `row` is the only supported type with values `True` or `False`

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 enforced and your groups are defined, you are ready to entitle groups of users to access specific packages, query data in specific databases and optionally 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.

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, including package deletion

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  │ name                               access  policies │ name    access  │ False    │ name   enabled  │
│ -------------------------------- │          │        │ --------------------------------  -----   -------   │ ------  ------- │          │ -----  -------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │        │ group1                             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 │          │        │ group2                             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 <name> <entity_type>

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

bash

Copy

╭──────────────────────────────────┬──────────┬────────┬─────────────────────────────────────────────────────┬─────────────────┬──────────┬─────────────────╮
│ entity                           │ entity   │ owner  │ groups                                              │ users           │ policies │ policy types    │
│                                  │ type     │        │                                                     │                 │ enabled  │                 │
├──────────────────────────────────┼──────────┼────────┼─────────────────────────────────────────────────────┼─────────────────┼──────────┼─────────────────┤
│ insights-demo                    │ package  │ OWNER  │ name                              access  policies  │ name    access  │ False    │ name   enabled  │
│ -------------------------------- │          │        │ --------------------------------  -----   -------   │ ------  ------- │          │ -----  -------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │        │group                               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 package and 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.
- 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> <entity_type>--name <NAME> to update the entity name. Only users with the Administrator role 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.