Configuring entitlements

This section provides a detailed description of the functionality available to a user or service account with the insights.entitlements.admin role when configuring entitlements.

References to users and assemblies

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.

When assemblies are referenced on this page, this refers to both assemblies created via the kdb Insights CLI and databases created from the kdb Insights Enterprise UI.

Entitlement fields

The following table describes the fields present in the json files returned when managing entitlements:

name	details
id	GUID to identify the entitlement. 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 assembly. This value is automatically generated and used by the system if it is not specified. Once defined, it cannot be changed as it is required for future updates.
entity	Name of the entity with which the entitlement is associated.
entityType	Either `assembly` or `package`.
groups	One or more lists of GUIDS and Access levels provided by Keycloak for groups of users that are enabled to query the entity.
owner	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.

Defining entitlements

Once the prerequisites are complete, entitlements is enabled and your groups are defined, you are ready to create your entitlements.

View groups

First, list the groups that can be associated with an assembly by calling the following:

kxi entitlement actors

[
    {
        "id": "ae3a8d5c-0afe-4fba-bbaf-dd962a76ad4a",
        "name": "marketing",
        "path": "/marketing"
    },
    {
        "id": "cf16d416-3b6f-423d-b179-561251b98644",
        "name": "research",
        "path": "/research"
    },
    {
        "id": "9c5c9129-023a-446c-86b0-bda7493717f6",
        "name": "ai",
        "path": "/research/ai"
    },
    {
        "id": "1af78449-3a6d-4e1c-9681-42e8c0a971b7",
        "name": "quantum",
        "path": "/research/ai/quantum"
    }
]

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.

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

Creating an entitlement

Once you know the IDs of the groups, you are ready to create an entitlement that allows users in those groups to query the assembly.

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	Unique GUID for the entity. Maintain this value for future updates. Use the `uuidgen` command to generate this value.
NAME	Name of the assembly, this must match the name of an existing assembly. Use `kxi entitlement update <ID> --name` to update the entity name if the name is changed.
TYPE	Currently only `assembly` is supported in the `TYPE` field.
GROUPID1,GROUPID2	List of GUIDs for the groups that will be entitled to access this entity.
ACCESS1,ACCESS2	Access permissions for the users of the groups entity and how they can interact with the entitlement .

You can view details of all entitlements or a single entitlement using the ID returned.

Viewing 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": "OWNER1",
        "groups": [
            {
                "id": "GROUPID1",
                "access": "ACCESS1"
            },
            {
                "id": "GROUPID2",
                "access": "ACCESS2"
            }
        ],
        "users": [
            {
                "id": "USERID1",
                "username": "USERNAME1",
                "access": "ACCESS1"
            },
            {
                "id": "USERID2",
                "username": "USERNAME2",
                "access": "ACCESS2"
            }
        ]
    },
    {
        "id": "ID2",
        "internalId":"InternalID2",
        "entity": "NAME2",
        "entityType": "assembly",
        "owner": "OWNER2",
        "groups": [
            {
                "id": "GROUPID3",
                "access": "ACCESS1"
            },
        ],
        "users": [
            {
                "id": "USERID3",
                "username": "USERNAME3",
                "access": "ACCESS1"
            }
        ]
    }
]

View a specific entitlement

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

kxi entitlement get <ID>

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

{
    "id": "ID",
    "entity": "NAME",
    "entityType": "assembly",
    "owner": "OWNER",
    "groups": [
        {
            "id": "GROUPID1",
            "access": "ACCESS1"
        },
        {
            "id": "GROUPID2",
            "access": "ACCESS2"
        }
    ],
}

Updating entitlements

When you need to change the list of users entitled to query the data from an assembly, you can take one of the following actions to implement that change:

Keycloak: a Keycloak administrator can add or remove users from a group that is entitled to access the assembly.
Data entitlements: you can edit entitlements using the following commands:
- 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.
    
    Renaming entities
    
    The entity name must match the assembly name. If it does not, use kxi entitlement update <ID> <TYPE>--name <NAME> to update the entity name. Only entitlements administrators can query data from entities with a mismatched name.
- kxi entitlement add-groups - adds one or more groups to the current list of groups
- kxi entitlement remove-groups- removes one or more groups from the current list of groups
- kxi entitlement delete - removes the entitlement altogether and stops all users, including the owner from querying the data.

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 will honour the previous set of entitlements.

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.