> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-feat-druid-driver-streaming.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Access policies

> Access policies control row-level and member-level security on cubes and views, restricting what data users can see.

## Parameters

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

* [`group`](#group) or [`groups`](#groups) define which groups a policy applies to.
* [`conditions`](#conditions) can be optionally used to specify when a policy
  takes effect.
* [`member_level`](#member_level) and [`row_level`](#row_level) parameters are used
  to configure [member-level][ref-dap-mls] and [row-level][ref-dap-rls] access.
* [`member_masking`](#member_masking) can be optionally used to configure
  [data masking][ref-dap-masking] for members not included in `member_level`.

<Info>
  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.
</Info>

### `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.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: marketing
          # ...

        - group: finance
          # ...
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

### `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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

    access_policy: [
      {
        groups: [`analysts`, `managers`],
        member_level: {
          includes: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

### `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][ref-sec-ctx] 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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  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: "*"
  ```

  ```javascript title="JavaScript" theme={null}
  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: `*`
        }
      }
    ]
  })
  ```
</CodeGroup>

#### 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`           | <code>\|\|</code>             |
| 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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  conditions:
    - if: "{ not userAttributes.is_blocked }"
    - if: "{ userAttributes.is_admin or userAttributes.is_EMEA_based }"
    - if: "{ userAttributes.groups.includes('admins') }"
  ```

  ```javascript title="JavaScript" theme={null}
  conditions: [
    { if: !userAttributes.is_blocked },
    { if: userAttributes.is_admin || userAttributes.is_EMEA_based },
    { if: userAttributes.groups.includes(`admins`) }
  ]
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

<Note>
  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](https://github.com/cube-js/cube/issues?q=is%3Aissue+label%3A%22data+modeling%3Aaccess+policies%22).
</Note>

### `member_level`

The optional `member_level` parameter, when present, configures [member-level
access][ref-dap-mls] 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                 |

<CodeGroup>
  ```yaml title="YAML" theme={null}
  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
  ```

  ```javascript title="JavaScript" theme={null}
  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`
          ]
        }
      }
    ]
  })
  ```
</CodeGroup>

Note that access policies also respect [member-level security][ref-mls] restrictions
configured via `public` parameters. See [member-level access][ref-dap-mls] to
learn more about policy evaluation.

### `member_masking`

The optional `member_masking` parameter, when present, configures [data
masking][ref-dap-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][ref-mask-dim]
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.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          member_level:
            includes:
              - status
              - count
          member_masking:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

### `row_level`

The optional `row_level` parameter, when present, configures [row-level
access][ref-dap-rls] 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][ref-sec-ctx].
All other users are disallowed from accessing any rows at all.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: state
                operator: equals
                values: [ "{ userAttributes.state }" ]
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

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:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: [ "{ userAttributes.country }", "{ userAttributes.customCountryProperty }" ]
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

For convenience, row filters are configured using the same format as [filters in
REST (JSON) API][ref-rest-query-filters] queries, allowing to use the same set of
[filter operators][ref-rest-query-ops], e.g., `equals`, `contains`, `gte`, etc.
You can also use `and` and `or` parameters to combine multiple filters into
[boolean logical operators][ref-rest-boolean-ops].

Note that access policies also respect [row-level security][ref-rls] restrictions
configured via the `query_rewrite` configuration option. See [row-level access][ref-dap-rls] to
learn more about policy evaluation.

## Using securityContext

The [`userAttributes`][ref-sec-ctx] object is only available in Cube Cloud platform. If you are using Cube Core or authenticating against [Core Data APIs][ref-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`.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={null}
  cube(`orders`, {
    // ...

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

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-views]: /reference/data-modeling/view

[ref-dap]: /docs/data-modeling/data-access-policies

[ref-dap-mls]: /docs/data-modeling/data-access-policies#member_level-access

[ref-dap-rls]: /docs/data-modeling/data-access-policies#row_level-access

[ref-mls]: /docs/data-modeling/access-control/member-level-security

[ref-rls]: /docs/data-modeling/access-control/row-level-security

[ref-sec-ctx]: /docs/data-modeling/access-control/context

[ref-core-data-apis]: /reference/core-data-apis

[ref-dap-masking]: /docs/data-modeling/data-access-policies#data-masking

[ref-mask-dim]: /reference/data-modeling/dimensions#mask

[ref-rest-query-filters]: /reference/core-data-apis/rest-api/query-format#filters-format

[ref-rest-query-ops]: /reference/core-data-apis/rest-api/query-format#filters-operators

[ref-rest-boolean-ops]: /reference/core-data-apis/rest-api/query-format#boolean-logical-operators