Skip to main content
Version: 9.2

Column-Level Security

Overview​

Column-Level Security allows administrators to restrict data access at the column level within a dataset to users belonging to one or more predefined roles. Users must be members of at least one of the assigned roles for Column-Level Security to view data for that column and reference it within any supported embedded widget. Column-Level Security is only supported for embedded widgets, and only for the following UI components:

  • Dashboards
  • Pixel-Perfect Reports

You can use Column-Level Security to hide entire columns of data from specific groups or user types, and also to eliminate the need to create separate datasets for specific groups of users.

  1. Define User Roles: Roles must be predefined within the platform in order to lock down specific columns of a dataset by user role. All users have access to all columns within a dataset by default.

  2. Apply Column-Level Security to Datasets: Column-Level Security must be explicitly set for each column of a dataset using a series of API endpoints. This step must be performed through API calls.

  3. Use Column-Level Security with Security Tokens: Developers embedding content with Qrvey’s user widget model must explicitly reference one or more of the predefined user roles within the JSON configuration object for that widget.

Configuring Column-Level Security​

Step 1: Define User Roles​

This step must be performed by a user with administrator credentials. Log in to the Admin Center and navigate to the Roles & Permissions UI. At least one user role must be defined here to use with Column-Level Security.

column-level-security

For more information about creating user roles in the Admin Center, refer to the Users & Permissions article.

Note: Do not use the predefined system “Administrators” and “Composers” roles for Column-Level Security.

Step 2: Apply Column-Level Security to Datasets​

Note: Column-Level Security can only be applied by means of API calls. Applying Column-Level Security to datasets within the Composer UI is not supported.

Use the Set Record and Column-Level Security endpoint to apply Column-Level Security to a dataset. If you need a column ID, use the Get Dataset endpoint. The “Get Dataset” endpoint will return the complete dataset definition for a specific dataset in JSON format, which can then be modified to include the Column-Level Security access roles.

Within the "Set Record and Column-Level Security Request", define the accessRoles property if it does not exist on the dataset column, and set its value to either the name or ID of the user role. You can optionally set the accessRoles property to an array of comma-delimited role names.

When applying Column-Level Security to a dataset column, the developer can use either the Role ID or the Role Name to define the accessRoles on the column and to pass the roles in the Widget configuration. However, the role ID and role name cannot be used simultaneously.

  • If the role ID is applied to the column accessRoles, then the role ID must be used in the roles attribute for widget configuration.
  • If the role name is applied to the column accessRoles, then the role name must be used in the roles attribute for widget configuration.

Notice the difference between the images in Step 1 (which demonstrates role ID) and Step 3 (which demonstrates role name). Choose one system for both the application of Column-Level Security and widget configuration.

column-level-security

Step 3: Pass User Roles in Widget Config Object​

This step entails declaring the roles that the user is a member of when constructing the JSON config object for the embedded widget. For more information about embedding widgets, see Introduction to Widgets. The JSON widget configuration object should be constructed on the back end to properly encrypt the widget configuration with the JWT token for security purposes. Define the roles property in the JSON config object and set the value to the name of the user role as a string. You can also use an array of strings to pass more than one role with the configuration object. The following JavaScript code provides an example.

column-level-security

This sample code is written in Javascript. However, you can make the JWT call in the back-end server-side web application development language of your choice. For more information about securely embedding Qrvey platform widgets within external web applications, see Embedding Widgets Using a Security Token.