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. For details about the security terminology used, refer to the Terminology section of the Authentication page.
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 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. |
internalId | GUID to uniquely identify the assembly. The actual value of this is unimportant and is auto generated by the system if not provided. Once defined, it cannot be changed 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 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. 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>:<ACCESS1>,<GROUPID2>:<ACCESS2>
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. |
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
You can view all the entitlements as follows:
kxi entitlement list
[
{
"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>
{
"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 groupskxi 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.