> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-alena-cub-2868-document-hierarchy-support-in-explore.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={"dark"}
  cubes:
    - name: orders
      # ...

      access_policy:
        - group: marketing
          # ...

        - group: finance
          # ...
  ```

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  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={"dark"}
  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>

### `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={"dark"}
  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={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          member_level:
            includes:
              - status
              - count
          member_masking:
            includes: "*"
  ```

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: state
                operator: equals
                values: [ "{ userAttributes.state }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...
      
      access_policy:
        - group: manager
          row_level:
            filters:
              - member: users_country
                operator: equals
                values: [ "{ userAttributes.country }", "{ userAttributes.customCountryProperty }" ]
  ```

  ```javascript title="JavaScript" theme={"dark"}
  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={"dark"}
  cubes:
    - name: orders
      # ...

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

  ```javascript title="JavaScript" theme={"dark"}
  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/rest-api/query-format#filters-format

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

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