Data Access Control

Managing Permissions in Model Files

Follow this comprehensive guide on managing data access within a model. Access Grants enable users to control access to topics and columns based on attributes, offering finer control over topics and limiting access to sensitive data. Access Filters allow for row-level permissions based on user attributes, useful for scenarios where users should only see their own data. The document includes syntax examples and implementation details for both mechanisms, along with practical examples and considerations for special user cases like administrators needing access to all data.

Access Grants

Access grants allow users to control access to a model’s topics and/or columns by utilizing user attributes. A user must have the necessary value assigned to their user attribute in order to gain access to the particular topic or field. Use case examples for implementing an access grant:

1. Finer control over access to topics.

   • Access to topics based on team assignment, i.e. the marketing team only sees the marketing topic and the finance team only sees finance topics.
   • Finer grain control over topics that present simpler data versus more granular and complicated data. This could be to provide a different level of access for Restricted Querier users vs Querier users.
   • Access based on regions, for example, limiting customer data access to regional sales teams.

2. Finer control over access to specific columns (fields).

   • Limiting access to Personally Identifiable Information (PII) fields.
   • Limiting access to financial fields.
   • Limiting access to other types of sensitive information.

Topic and Column level permissions can be controlled by creating an access_grant: in the model file, see this access grant documentation for more details. Omni will map user-specific variables, user_attributes, to a corresponding allowed value defined in the the topic or field definition. Based on the listed allowed values and the user querying that topic Omni will determine if the user has the necessary permissions to access that topic.

Example

Defining the access_grants: in the Model:

access_grants:
  nw_region:
    user_attribute: region
    allowed_values: [washington, idaho, oregon, wyoming, alaska]
  finance:
    user_attribute: team
    allowed_values: [Finance]
  marketing:
    user_attribute: team
    allowed_values: [Marketing]

Implementing the required_access_grants: on the Topic:

topics:
  order_items:
    label: Transactional
    joins:
      inventory_items:
        products:
          distribution_centers: {}
      users: {}
    required_access_grants: [ nw_region ]

  products:
    joins:
      distribution_centers: {}
    required_access_grants: [ marketing, finance ]

  users:
    joins: {}
    required_access_grants: [ finance ]

Implementing the required_access_grants: on the Column (field):

  margin:
    sql: ${order_items.sale_price} - ${products.cost}
    format: CURRENCY
    description: margin = sale price - cost
    required_access_grants: [ finance ]
    
  revenue:
    label: Gross Receipts
    extends: [ order_items.sale_price ]
    required_access_grants: [ finance ]

Access Filters

Access Filters allow developers to control row-level permissions on a field. For example, different users may have access to only their own fields within the underlying schema, this may happen when building customer facing applications and transactions are collected across customers in a single table vs a schema per table. Use case examples for implementing access filters:

• Only showing a client the data related to their own brand
• A doctor in a hospital system only seeing their own patient data

Row level permissions can be controlled via the access_filter: in Omni. By mapping user-specific variables, user_attributes, to a corresponding field, Omni can limit all exploration inside a given topic to only rows that match the user's associated value. Below is a simple example, to filter the order_items topic so that each brand can only see their own transactions, and the associated metadata for each transaction:

Syntax

topics:
  <view_name>:
    joins:
      <view_name>:
        <view_name_to_join>: {}
      <view_name>:
        view_name_to_join>: {}
    access_filters:
      - field: <view_name.field_name>
        user_attribute: <user_attribute_name>
        values_for_unfiltered: [<default_value_for_unrestricted_users>]

Important info about Access Filters

Users may want to implement restrictions to data with access filters but still allow specific users (i.e. an admin) to access to see all data for that field. In this case, you can set a special value on those particular user's user attribute and add it to the parameter values_for_unfiltered which would not apply the access filter to these users. In the example above, all users that have a value of is_admin for the user attribute, Region, would not see any filtered results.

Users with no value in the associated user_attribute, in this case region = null will error as Omni expects a value for any assigned access_filters.

Example

topics:
  order_items:
    joins:
      orders:
        user: {}
      inventory_items:
        products: {}
    access_filters:
      - field: products.brand
        user_attribute: customer
        values_for_unfiltered: [is_admin]

Here any query would require a join to order > inventory_items > products, and then the query would be filtered using:

• WHERE products.brand = <the_value_in_user_attribute_brand>

Limiting access to only data that has that brand. This can be particularly useful in only allowing clients to see their own specific data related to their brand.