Access policies

Parameters

The access_policy parameter should define a list of access policies. Each policy can be configured using the following parameters:

group or groups define which groups a policy applies to.
conditions can be optionally used to specify when a policy takes effect.
member_level and row_level parameters are used to configure member-level and row-level access.
member_masking can be optionally used to configure data masking for members not included in member_level.

When you define access policies for specific groups, access is automatically denied to all other groups. You don’t need to create a default policy that denies access.

`group`

The group parameter defines which group a policy applies to. To define a policy that applies to all users regardless of their groups, use the any group shorthand: group: "*". In the following example, two access policies are defined for users with marketing or finance groups, respectively.

cubes:
  - name: orders
    # ...

    access_policy:
      - group: marketing
        # ...

      - group: finance
        # ...

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `marketing`,
      // ...
    },
    {
      group: `finance`,
      // ...
    }
  ]
})

`groups`

The groups parameter (plural) allows you to apply the same policy to multiple groups at once by providing an array of group names. In the following example, a single policy applies to both analysts and managers groups:

cubes:
  - name: orders
    # ...

    access_policy:
      - groups: [analysts, managers]
        member_level:
          includes: "*"

cube(`orders`, {
  // ...

  access_policy: [
    {
      groups: [`analysts`, `managers`],
      member_level: {
        includes: `*`
      }
    }
  ]
})

`conditions`

The optional conditions parameter, when present, defines a list of conditions that should all be true in order for a policy to take effect. Each condition is configured with an if parameter that is expected to reference the security context or user attributes. In the following example, a permissive policy for all groups will only apply to EMEA-based users, as determined by the is_EMEA_based user attribute:

cubes:
  - name: orders
    # ...

    access_policy:
      - group: "*"
        conditions:
          - if: "{ userAttributes.is_EMEA_based }"
        member_level:
          includes: "*"

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `*`,
      conditions: [
        { if: userAttributes.is_EMEA_based }
      ],
      member_level: {
        includes: `*`
      }
    }
  ]
})

You can use the conditions parameter to define multiple policies for the same group. In the following example, the first policy provides access to a subset of members to users in the manager group who are full-time employees while the other one provides access to all members to users in the manager group who are full-time employees and have also completed a data privacy training:

cubes:
  - name: orders
    # ...

    access_policy:
      - group: manager
        conditions:
          - if: "{ userAttributes.is_full_time_employee }"
        member_level:
          includes:
            - status
            - count

      - group: manager
        conditions:
          - if: "{ userAttributes.is_full_time_employee }"
          - if: "{ userAttributes.has_completed_privacy_training }"
        member_level:
          includes: "*"

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      conditions: [
        { if: userAttributes.is_full_time_employee }
      ],
      member_level: {
        includes: [
          `status`,
          `count`
        ]
      }
    },
    {
      group: `manager`,
      conditions: [
        { if: userAttributes.is_full_time_employee },
        { if: userAttributes.has_completed_privacy_training }
      ],
      member_level: {
        includes: `*`
      }
    }
  ]
})

Supported operators

The if expression must evaluate to a boolean. The syntax you can use inside it depends on the data model format:

In YAML data models, the expression inside { } is evaluated as a Python expression. Only logical operators, member access, and method calls are supported.
In JavaScript data models, the expression is evaluated as a JavaScript expression, so a broader set of operators is available.

The following operators and constructs are supported:

Operator	Python (YAML)	JavaScript
Logical AND	`and`	`&&`
Logical OR	`or`	`\|\|`
Logical NOT	`not`	`!`
Member access	`.`	`.`
Method call (e.g., `includes`)	`.includes(…)`	`.includes(…)`
Equality and inequality	—	`===`, `!==`, `==`, `!=`
Comparison	—	`<`, `>`, `<=`, `>=`
Arithmetic	—	`+`, `-`, ``, `/`, `%`, `*`
Ternary	—	`? :`
Optional chaining	—	`?.`

For example, the following policy applies to users who are not blocked, are either administrators or based in the EMEA region, and belong to the admins group. Each requirement is expressed as a separate condition, and all conditions must be true for the policy to take effect:

conditions:
  - if: "{ not userAttributes.is_blocked }"
  - if: "{ userAttributes.is_admin or userAttributes.is_EMEA_based }"
  - if: "{ userAttributes.groups.includes('admins') }"

conditions: [
  { if: !userAttributes.is_blocked },
  { if: userAttributes.is_admin || userAttributes.is_EMEA_based },
  { if: userAttributes.groups.includes(`admins`) }
]

Prefer decomposing a condition chained with logical AND into separate conditions. Since conditions are combined with AND, the result is equivalent but easier to read and maintain.

The set of operators supported in JavaScript data models is currently broader than in YAML data models. If you’d like to use additional operators in YAML, please request support by opening an issue on GitHub.

`member_level`

The optional member_level parameter, when present, configures member-level access for a policy by specifying allowed or disallowed members. You can either provide a list of allowed members with the includes parameter, or a list of disallowed members with the excludes parameter. There’s also the all members shorthand for both of these paramaters: includes: "*", excludes: "*". In the following example, member-level access is configured this way:

Group	Access
`manager`	All members except for `count`
`observer`	All members except for `count` and `count_7d`
`guest`	Only the `count_30d` measure
All other groups	No access to this cube at all

cubes:
  - name: orders
    # ...
    
    access_policy:
      - group: manager
        member_level:
          # Includes all members except for `count`
          excludes:
            - count
      
      - group: observer
        member_level:
          # Includes all members except for `count` and `count_7d`
          excludes:
            - count
            - count_7d
      
      - group: guest
        # Includes only `count_30d`, excludes all other members
        member_level:
          includes:
            - count_30d

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      // Includes all members except for `count`
      member_level: {
        excludes: [
          `count`
        ]
      }
    },
    {
      group: `observer`,
      // Includes all members except for `count` and `count_7d`
      member_level: {
        excludes: [
          `count`,
          `count_7d`
        ]
      }
    },
    {
      group: `guest`,
      // Includes only `count_30d`, excludes all other members
      member_level: {
        includes: [
          `count_30d`
        ]
      }
    }
  ]
})

Note that access policies also respect member-level security restrictions configured via public parameters. See member-level access to learn more about policy evaluation.

`member_masking`

The optional member_masking parameter, when present, configures data masking for a policy. It requires member_level to be defined in the same policy. Members included in member_level get full access. Members not in member_level but included in member_masking return masked values instead of being denied. The mask value is defined by the mask parameter on each dimension or measure. You can provide a list of maskable members with includes, or a list of non-maskable members with excludes. Use "*" as a shorthand for all members.

cubes:
  - name: orders
    # ...
    
    access_policy:
      - group: manager
        member_level:
          includes:
            - status
            - count
        member_masking:
          includes: "*"

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      member_level: {
        includes: [
          `status`,
          `count`
        ]
      },
      member_masking: {
        includes: `*`
      }
    }
  ]
})

`row_level`

The optional row_level parameter, when present, configures row-level access for a policy by specifying filters that should apply to result set rows. In the following example, users in the manager group are allowed to access only rows that have the state dimension matching the state from the security context. All other users are disallowed from accessing any rows at all.

cubes:
  - name: orders
    # ...
    
    access_policy:
      - group: manager
        row_level:
          filters:
            - member: state
              operator: equals
              values: [ "{ userAttributes.state }" ]

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      row_level: {
        filters: [
          {
            member: `state`,
            operator: `equals`,
            values: [ userAttributes.state ]
          }
        ]
      }
    }
  ]
})

You can also pass multiple values in the values array to match against several user attributes at once. This is useful when you need to check a dimension against more than one attribute, for example, when a user may have access based on multiple properties:

cubes:
  - name: orders
    # ...
    
    access_policy:
      - group: manager
        row_level:
          filters:
            - member: users_country
              operator: equals
              values: [ "{ userAttributes.country }", "{ userAttributes.customCountryProperty }" ]

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      row_level: {
        filters: [
          {
            member: `users_country`,
            operator: `equals`,
            values: [
              userAttributes.country,
              userAttributes.customCountryProperty
            ]
          }
        ]
      }
    }
  ]
})

For convenience, row filters are configured using the same format as filters in REST (JSON) API queries, allowing to use the same set of filter operators, e.g., equals, contains, gte, etc. You can also use and and or parameters to combine multiple filters into boolean logical operators. Note that access policies also respect row-level security restrictions configured via the query_rewrite configuration option. See row-level access to learn more about policy evaluation.

Using securityContext

The userAttributes object is only available in Cube Cloud platform. If you are using Cube Core or authenticating against Core Data APIs directly, you won’t have access to userAttributes. Instead, you need to use securityContext directly when referencing user attributes in access policies (e.g., in row_level filters or conditions). For example, use securityContext.userId instead of userAttributes.userId.

cubes:
  - name: orders
    # ...

    access_policy:
      - group: manager
        row_level:
          filters:
            - member: country
              operator: equals
              values: [ "{ securityContext.country }" ]

cube(`orders`, {
  // ...

  access_policy: [
    {
      group: `manager`,
      row_level: {
        filters: [
          {
            member: `country`,
            operator: `equals`,
            values: [ securityContext.country ]
          }
        ]
      }
    }
  ]
})

Data Modeling

Configuration

Core Data APIs

Embed APIs

Other APIs

JavaScript SDK

Parameters

`group`

`groups`

`conditions`

Supported operators

`member_level`

`member_masking`

`row_level`

Using securityContext

​Parameters

​group

​groups

​conditions

​Supported operators

​member_level

​member_masking

​row_level

​Using securityContext

Parameters

`group`

`groups`

`conditions`

Supported operators

`member_level`

`member_masking`

`row_level`

Using securityContext