Data Entitlements Quickstart - BETA
This page shows you how to create a group of users named demo-users
, add users to that group, and entitle that group to query all the data from the database in the insights-demo
package.
If necessary, follow the instructions referred to in the Guided walkthrough for details on how to create and populate the insights-demo
package.
Ensure you have met the prerequisites before using this quickstart.
To configure entitlements you need to either: - have the Administrator role, or - have the Maintainer role and own the package that contains the database.
Assuming you already have the insights-demo
package deployed, do the following to configure entitlements.
Create a group and assign users
Assuming you are not using Microsoft Entra ID to allow your users to log into kdb Insights Enterprise, you can use either the CLI or the Keycloak UI to create groups and assign users. In this quickstart we will document the use of the CLI. Details on how to use the keycloak UI are listed here
Note
To manage groups and users you need to provide credentials for a keycloak admin user as described here.
-
Start an interactive session for entitlement management by calling the
kxi entitlement manage
command:kxi entitlement manage
-
The session lists entities that can be entitled. Use the tab or the up and down arrows to select the record with EntityType of
database
and Entity ofinsights-demo
and press Enter. -
The session lists groups that can be entitled.
-
If
demo-users
group does not already exist:-
Press Ctrl+E to create a new group.
-
If you have not set the keycloak admin password in your cli-config you will be asked for the password.
-
Type in
demo-users
and press ** Enter**.
-
-
To add existing users to the
demo-users
group:-
Select
demo-users
and press Enter -
Use the tab or the up and down arrows to select Users with Group [admin only] and press Enter.
-
The session lists users that can be added or removed from the group.
-
Use the tab or the up and down arrows to select the users and press TAB to add or remove that user from a group.
-
Press Enter to save the changes.
-
-
-
Use the following command to create the
demo-users
group:kxi group create demo-users
-
Assign groups to users:
-
For a new user you can add a group as part of the
kxi user create
command and ensure the user has the Viewer role, at a minimum:kxi user create $USERNAME --password $PASSWORD --groups demo-users kxi user assign-roles $USERNAME --roles insights.role.viewer
Replace the following variables with the appropriate values for your use case:
$USERNAME
: Username to the assign group to.$PASSWORD
: Password for the new user.
-
For an existing user, you can use the
kxi user assign-group
command:kxi user assign-groups $USERNAME --groups demo-users
$USERNAME
: Username to the assign group to.
-
Note
Each user requires the Viewer role, at a minimum, as a user needs both role-based permissions and database entitlements to insights-demo
to view the data. Follow the guide here to modify the roles.
Configure the entitlements
-
Entitle the
demo-users
group to query the data in the database:-
Start an interactive session for entitlement management by calling the
kxi entitlement manage
command:kxi entitlement manage
-
The session lists entities that can be entitled. Use the tab or the up and down arrows to select the record with EntityType of
database
and Entity ofinsights-demo
and press Enter. -
The session lists groups that can be entitled. Use the tab or the up and down arrows to select the demo-users group and press Enter.
-
The session lists access levels that you can assign to groups. Use the up and down arrows to select Read and press the spacebar to select Read access and press Enter to save the changes.
Note
Package entitlements are the only entitlements type that enforces the different access levels. For data entitlements, you must ensure at least one of them is selected.
-
The session displays a list of groups. The Access column is now set to
R
for the "demo-users" group. -
Press Ctrl+B to go back to the list of entities.
-
Press Q to exit the interactive session.
-
Find the Group ID provided by Keycloak for the new "demo-users" group.
To do this, call the
kxi entitlement actors
command:kxi entitlement actors
╭─────────────────────────────────┬─────────────┬──────────────────────┬────────────╮ │ actor │ path │ members │ admingroup │ ├─────────────────────────────────┼─────────────┼──────────────────────┼────────────┤ │ demo-users │ /demo-users │ name access │ False │ │ ------------------------------- │ │ ----------- ------- │ │ │ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXX │ │ demo-user-1 R │ │ │ │ │ demo-user-2 R │ │ ╰─────────────────────────────────┴─────────────┴──────────────────────┴────────────╯
-
Store the group ID defined in the actor column, below the name of the group to a variable called
$GROUPID
. -
Choose an access level and store it in a variable called
$ACCESS
. The access levels available are defined here.Note
The package entitlements is the only entitlements type that enforces the different access levels. For data entitlements you just need to make sure at least one of them is selected.
-
Add the group to the query entitlements for the
insights-demo
package.kxi entitlement add-groups insights-demo database $GROUPID:$ACCESS
-
Call
kxi entitlement get
to see your changes:kxi entitlement get insights-demo database
╭──────────────────────────────────┬──────────┬────────┬─────────────────────────────────────────────────────┬─────────────────┬──────────┬─────────────────╮ │ entity │ entity │ owner │ groups │ users │ policies │ policy types │ │ n │ type │ │ │ │ enabled │ policy types │ ├──────────────────────────────────┼──────────┼────────┼─────────────────────────────────────────────────────┼─────────────────┼──────────┼─────────────────┤ │ insights-demo │ database │ owner │ id access policies │ name access │ False │ name enabled │ │ -------------------------------- │ │ │ -------------------------------- ----- ------- │ ------ ------- │ │ ----- -------- │ │ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │ │ │ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX R │ owner ARWX │ │ row False │ │ │ │ │ │ user1 R │ │ row False │ ╰──────────────────────────────────┴──────────┴────────┴─────────────────────────────────────────────────────┴─────────────────┴──────────┴─────────────────╯
In this example
user1
is in thedemo-users
group and therefore as Read access to the database.
-
Once these steps have been completed and a short period of time has been allowed for the synchronization of the change across the system, any user that is part of the demo-users
group can now query data in the insights-demo database using REST, the Query window and Views.
Refer to the kdb Insights CLI documentation for full details on the kxi entitlement
command and Entitlements fields for an explanation of the fields returned by the commands executed above.
Next steps
- Learn how to modify an entitlement in the configuration guide.
- Add Row level entitlements to further fine tune the data access.