Configuring data 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. Please see here for details of security terminology that is used.

When assemblies are referenced here, 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 uniquely identify the assembly. The actual value of this is unimportant but it cannot be changed once it has been defined as it is required for later updates.
entity	Name of the entity with which the entitlement is associated.
entityType	The only option currently available is `assembly`.
groups	One or more GUIDs 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. Not currently used and set to "00000000-0000-0000-0000-000000000000"
users	One or more GUIDs provided by Keycloak for the users that are in the groups associated with the entity.

Defining entitlements for an assembly

Once the prerequisites are complete you will have data entitlements enabled and your groups are defined. You are now ready to create your data 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 using the prerequisites guide here.

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>,<GROUPID2>

The values specified are as follows:

values	details
ID	Unique GUID for the entity. The actual value of this is unimportant, but should be maintained for updates later. You can use the `uuidgen` command to generate one.
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.

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

Viewing entitlements

View all entitlements

You can view all the entitlements as follows:

kxi entitlement list

[
    {
        "id": "ID1",
        "entity": "NAME1",
        "entityType": "assembly",
        "owner": "OWNER1",
        "groups": [
            "GROUPID1",
            "GROUPID2"
        ],
        "users": [
            {
                "id": "USERID1",
                "username": "USERNAME1"
            },
            {
                "id": "USERID2",
                "username": "USERNAME2"
            }
        ]
    },
    {
        "id": "ID2",
        "entity": "NAME2",
        "entityType": "assembly",
        "owner": "OWNER2",
        "groups": [
            "GROUPID3"
        ],
        "users": [
            {
                "id": "USERID3",
                "username": "USERNAME3"
            }
        ]
    }
]

View a specific entitlement

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

kxi entitlement get <ID>

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

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> --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, it will obey the previous entitlement state.