Configuring Entitlements

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

References to users

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 `assembly` 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
`assembly`	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:

kxi entitlement actors

[
    {
        "id": "ae3a8d5c-0afe-4fba-bbaf-dd962a76ad4a",
        "name": "marketing",
        "path": "/marketing"
        "AdminGroup":false,
        "Members":[
            {
            "id":"ff8dd434-0edd-442d-99d9-32f25a0b6ff6",
            "username":"marketinguser1",
            "access":"ARWX"
            },
            {
            "id":"8fc32c16-f771-4d27-8294-46f619f57c36",
            "username":"marketinguser2",
            "access":"ARWX"
            }
        ]
    },
    {
        "id": "cf16d416-3b6f-423d-b179-561251b98644",
        "name": "research",
        "path": "/research"
        "AdminGroup":false,
        "Members":[
            {
            "id":"ff8dd434-0edd-442d-99d9-32f25a0b6ff6",
            "username":"researchuser1",
            "access":"RWX"
            }
        ]
    }
]

If no groups are returned

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
id	GUID provided by Keycloak for the group.
name	Group name provided by Keycloak.
path	Path to group indicating subgroup structure.
Members	List of users in the group including their id, name and access levels.

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.

Using assembly instead of package

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:

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 `assembly` and `package` are supported in the `TYPE` field.
GROUPID1,GROUPID2	List of GUIDs for the groups that will be 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.

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	Admin access

Policies

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

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:

kxi entitlement list

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

[
    {
        "id": "ID1",
        "internalId":"InternalID1",
        "entity": "NAME1",
        "entityType": "assembly",
        "owner":{
            "id":"OwnerID",
            "username":"OWNER"
        },
        "groups": [
            {
                "id": "GROUPID1",
                "access": "ACCESS1"
            },
            {
                "id": "GROUPID2",
                "access": "ACCESS2"
            }
        ],
        "users": [
            {
                "id": "USERID1",
                "username": "USERNAME1",
                "access": "ACCESS1"
            },
            {
                "id": "USERID2",
                "username": "USERNAME2",
                "access": "ACCESS2"
            }
        ],
        "policiesEnabled":false,
        "policyTypes":{
        }
    },

    {
        "id": "ID2",
        "internalId":"InternalID2",
        "entity": "NAME1",
        "entityType": "package",
        "owner":{
            "id":"OwnerID",
            "username":"OWNER"
        },
        "groups": [
            {
                "id": "GROUPID3",
                "access": "ACCESS1"
            },
        ],
        "users": [
            {
                "id": "USERID3",
                "username": "USERNAME3",
                "access": "ACCESS1"
            }
        ]
        "policiesEnabled":false,
        "policyTypes":{
        }
    }
]

View a specific entitlement

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

kxi entitlement get <ID> assembly

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

[
    {
        "id": "ID",
        "entity": "NAME",
        "entityType": "assembly",
        "owner": {
            "id": "OWNERID", 
            "username": "owner"
        },
        "groups": [
            {
                "id": "GROUPID1",
                "access": "ACCESS1"
            },
            {
                "id": "GROUPID2",
                "access": "ACCESS2"
            }
        ],
        "users": [
            {
                "id": "USERID1",
                "username": "USERNAME1",
                "access": "ACCESS1"
            }
        ]
        "policiesEnabled":false,
        "policyTypes":{
        }
    }
]

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
  
  This 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.
    
    Renaming entities
    
    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.
- kxi entitlement delete - removes the entitlement altogether and stops all users, except the owner and users with the insights.entitlements.admin from querying the data.

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.