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 provided follows the workflow below:

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

Refer to the instructions in the Guided walkthrough for details on how to create and populate the insights-demo package.

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

After a user has been created, you can use the Interactive Session in the CLI with the kxi entitlement manage command to add users to groups.

To create new users, use the kxi user create command and ensure the user has the Viewer role, at a minimum:
```
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:
```
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 Ctrl+B to go back to the list of entities.
7. 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:
```
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:
```
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:
```
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, subway and weather tables, follow the steps below:

If you have not done so already, pull the package from the environment:
```
kxi pm pull insights-demo 
```
Teardown the current version of the package:
```
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 you apply to the tables.
Add a reference to the da.q file to the package manifest.yaml file.
```
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 two exact match examples using = and like.
```
// @policy.name("queenscrimeborough")
queenscrimeborough:{[borough]borough like"QUEENS"}

// @policy.name("queenssubwayborough")
queenssubwayborough:{[route_long_name]route_long_name like"*Queens*"}

// @policy.name("queensweatherborough")
queensweatherborough:{[borough]borough =`Queens}
```
Note

health does not need a policy created as it uses the built-in _allRows policy.
You can bump the version of your package if you wish. The example below increases the minor version:
```
kxi package checkpoint insights-demo --bump minor
```
Push the updated package to kdb Insighsts Enterprise and redeploy:
```
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:
```
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:
```
kxi entitlement manage
```
Turn on 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. 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.
1. Use the tab or the up and down arrows to select Policy Mapping, and press Enter.
2. Use the tab or the up and down arrows to select Create/Append policies to an asset, and press Enter.
3. Add four policies, one per table:
  
  asset name policy type policy
  
  crime row queens-crimeborough
  
  subway row queens-subwayborough
  
  weather row queens-weatherborough
  
  health 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.

Find the group ID for queens-users to use in the CLI commands:
```
kxi entitlement actors
```
Store the group ID defined in the actor column below the queens-users to a variable called $GROUPID.

Turn on row level entitlements for the insights-demo database:

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:
```
kxi entitlement add-groups insights-demo database $GROUPID:R
```

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

kxi entitlement policy-mapping add insights-demo database --group $GROUPID --policy-type row --asset health --policies _allRows
kxi entitlement policy-mapping add insights-demo database --group $GROUPID --policy-type row --asset crime --policies queenscrimeborough
kxi entitlement policy-mapping add insights-demo database --group $GROUPID --policy-type row --asset subway --policies queenssubwayborough
kxi entitlement policy-mapping add insights-demo database --group $GROUPID --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 table contains.

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

kxi entitlement get insights-demo

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

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

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.

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