Row-Level Entitlements Quickstart

This page provides an example of how to configure row-level access for the database in the insights-demo package.

The example follows this workflow:

Create a group of users named queens-users
Add users to the created group.
Entitle the group to query rows in the crimeand subway tables, only where the borough is "Queens".
Entitle the group to query all the data in the weather table.

Refer to the instructions in the Create a Database for details on how to create and populate the insights-demo package.

Important

Ensure you have met the entitlements prerequisites before continuing with 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, follow the steps below to configure entitlements.

Create a group and assign users

If you are not using Microsoft Entra ID or another Identity provider (IdP) 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 document the use of the CLI. For details on how to use the keycloak UI, refer to managing groups.

Note

To manage groups and users, you need to provide credentials for a keycloak admin user as described in user management authentication.

Using an interactive session in the CLI

CLI

To create new users, use the kxi user create command and ensure the user has the Viewer role, at a minimum:
bash
Copy
```
kxi user create $USERNAME --password $PASSWORD
kxi user assign-roles $USERNAME --roles insights.role.viewer
```
Replace the following variables with the appropriate values for your use case:
- $USERNAME: Username of the user you want to assign a group to.
- $PASSWORD: Password for the new user.
Start an interactive session for entitlement management by using the kxi entitlement manage command:
bash
Copy
```
kxi entitlement manage
```
The session lists entities that you can manage. Use the tab or the up and down arrows to select the record with EntityType of database and Entity of insights-demo, and press Enter.
The session lists groups that can be entitled.
If the queens-users group does not already exist:
1. Press Ctrl+E to create a new group
2. If you have not set the Keycloak admin password in your CLI configuration, you are prompted to insert the password.
3. Type in queens-users and press Enter.
To add existing users to queens-users
1. Select queens-users and press Enter
2. Use the tab or the up and down arrows to select Users with Group [admin only], and press Enter.
3. The session lists users that can be added or removed from the group.
4. 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
5. Press Enter to save the changes.
6. Press Q to exit the interactive session.

If the queens-users group does not already exist, use the following command to create the queens-users group:
bash
Copy
```
kxi group create queens-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:
bash
Copy
```
kxi user create $USERNAME --password $PASSWORD --groups queens-users
kxi user assign-roles $USERNAME --roles insights.role.viewer
```
Replace the following variables with the appropriate values for your use case:
- $USERNAME: Username of the user you want to assign a group to.
- $PASSWORD: Password for the new user.
For an existing user, you can use the kxi user assign-group command to assign a group:
bash
Copy
```
kxi user assign-groups $USERNAME --groups queens-users
```
- $USERNAME: Username of the user you want to assign a group to.

Ensure that each user added to the group has the Viewer role, at a minimum, as a user needs both role-based permissions and database entitlements to insights-demo to view the data. Refer to the guide on assigning roles to modify the roles.

Add the row policies to the package

To create the row policies in the insights-demo package for the crime and subway tables, follow the steps below:

If you have not done so already, pull the package from the environment:
bash
Copy
kxi pm pull insights-demo
Tear down the current version of the package:
bash
Copy
kxi pm teardown insights-demo
Add a text file to the insights-demo package folder and name it da.q. This file will include the policies to apply to the tables.
Add a reference to the da.q file to the package manifest.yaml file.
bash
Copy
entrypoints: data-access: da.q
Add policies to the da.q file with the convention // @policy.name:

Note

Refer to the guides on the like keyword and regular expressions for guidance on creating policies. The policies below include a regular expression and an exact match examples using like.
bash
Copy
// @policy.name("queenscrimeborough") queenscrimeborough:{[borough]borough like"QUEENS"} // @policy.name("queenssubwayborough") queenssubwayborough:{[route_long_name]route_long_name like"*Queens*"}
Note

weather does not need a policy created as you will be using the built-in _allRows policy to entitle the group to see all rows in the table.
You can bump the version of your package if you wish. The example below increases the minor version:
bash
Copy
kxi package checkpoint insights-demo --bump minor
Push the updated package to kdb Insighsts Enterprise and redeploy:
bash
Copy
kxi pm push --force --deploy insights-demo
List the policies in the insights-demo package on kdb Insighsts Enterprise to ensure it has been updated and includes the policies you have defined:
bash
Copy
kxi pm list udf --filter package=insights-demo
Note

This command returns all User Defined Functions (UDFs) within the specified package of which row-level policies are a special kind of UDF.

Configure entitlements

To entitle the queens-users group to query a subset of data in the database, follow the steps below:

Using an interactive session in the CLI

CLI

Start an interactive session for entitlement management by using the kxi entitlement manage command:
bash
Copy
```
kxi entitlement manage
```
Enable row-level entitlements for the insights-demo database:
1. Press Ctrl+t to switch to the policy management mode
2. 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 of insights-demo, and press Enter.
3. The session lists actions that can be taken. Use the tab or the up and down arrows to select Enable Policies, and press Enter.
4. Press the spacebar to select Enabled and press Enter to save the changes.
5. The session lists actions that can be taken. Use the tab or the up and down arrows to select Manage Policy Types, and press Enter.
6. Press the spacebar to select row and press Enter to save the changes.
7. The session lists actions that can be taken. Use the tab or the up and down arrows to select Back, and press Enter.
8. Press Ctrl+t to switch back to the group management mode
Entitle the queens-users group to read data from the insights-demo database:
1. 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 of insights-demo, and press Enter.
2. Use the tab or the up and down arrows to select the queens-users group, and press Enter.
3. The session lists actions that can be taken. Use the tab or the up and down arrows to select Access Level, and press Enter.
4. 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.

Associate the row policies defined in the package with the appropriate tables in the insights-demo package and the queens-users group.

Use the tab or the up and down arrows to select Policy Mapping, and press Enter.
Use the tab or the up and down arrows to select Create/Append policies to an asset, and press Enter.
Add three policies, one per table:

asset name	policy type	policy
crime	row	queens-crimeborough
subway	row	queens-subwayborough
weather	row	_allRows

Note

_allRows is a predefined policy that can be associated with any table and allows a group of users access to all the rows that table contains.

Press Ctrl+B to go back to the list of entities.
Press Q to exit the interactive session.

Enable row-level entitlements for the insights-demo database:

bash

Copy

kxi entitlement policies-enable insights-demo database

kxi entitlement policy-mapping enable insights-demo database --policy-types row

Entitle the queens-users group to read data from the insights-demo database:
bash
Copy
```
kxi entitlement add-groups insights-demo database queens-users:R
```

Associate the row policies defined in the package with the appropriate tables in the insights-demo package and the queens-users group.

bash

Copy

 kxi entitlement policy-mapping add insights-demo database --group queens-users --policy-type row --asset health --policies _allRows
 
 kxi entitlement policy-mapping add insights-demo database --group queens-users --policy-type row --asset crime --policies queenscrimeborough
 
 kxi entitlement policy-mapping add insights-demo database --group queens-users --policy-type row --asset subway --policies queenssubwayborough
 
 kxi entitlement policy-mapping add insights-demo database --group queens-users --policy-type row --asset weather --policies queensweatherborough

Note

_allRows is a predefined policy that can be associated with any table and allows a group of users access to all the rows that the table contains.

You can review the database entitlements you have defined for insights-demo using the CLI as follows:

bash

Copy

kxi entitlement get insights-demo database

bash

Copy

╭──────────────────────────────────┬──────────┬─────────┬──────────────┬───────────────────┬──────────┬──────────────────┬────────────────────────────────────────╮
│ entity                           │ entity   │ owner   │ groups       │ users             │ policies │ policy types     │ policies                               │
│                                  │ type     │         │              │                   │ enabled  │                  │                                        │
├──────────────────────────────────┼──────────┼─────────┼──────────────┼───────────────────┼──────────┼──────────────────┼────────────────────────────────────────┤
│ insights-demo                    │ database │ owner   │ queens-users │ name     access   │ True     │ name    enabled  │ table    policy                        │
│ -------------------------------- │          │         │              │ ------   -------- │          │ ------  -------- │ ------   ----------------------------- │
│ XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX │          │         │              │ owner    ARWX     │          │ row     True     │ crime    queenscrimeborough            │
│                                  │          │         │              │                   │          │                  │                       │
│                                  │          │         │              │                   │          │                  │ subway   queenssubwayborough           │
│                                  │          │         │              │                   │          │                  │ weather  _allRows            │
╰──────────────────────────────────┴──────────┴─────────┴──────────────┴───────────────────┴──────────┴──────────────────┴────────────────────────────────────────╯

Once these changes have been actioned, users in the queens-users group can query all the data in the weather table and can view only rows in crimeand subway where the borough is set to "Queens".

Note

Refer to Change synchronization for details about the time kdb Insights Enterprise takes to action any updates

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.