Skip to content

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.