> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Atoti Access Control

In Atoti, it is possible to filter and transform the information differently for
different users or user groups. For example, one can make European users see only the
data regarding Europe, or see all the prices in €. It is also possible to hide dimensions and hierarchies from some users or user groups.
All these context-dependent elements can be configured through the so-called
[context values](../cube/context_values): in particular, the values of interest are
subcube properties and mdx contexts.

## Entitlements apply through context values

Subcube properties and mdx contexts are controlled by context values that
are assigned after authentication and at each query start.

Once authenticated, users are thus assigned a set of context values depending on their roles that
define, for example, the resources they can access, or change how the results are computed.

Then, at each query start, a Spring filter (the `ContextValueFilter`) calls Atoti's
`ContextValueManager`. The latter provides the context values that are then attached to
the context of this query, and thus define the subcube properties.

### `ContextValueManager`: how context values are attributed

When there are several possible values for a context value (for example, the user is a European user,
but they set an option to see the prices in US dollars), the `ContextValueManager` gives priority
to local transient values, then to global transient values, then to the values set through
the `IActivePivotContentService`, and finally to the values set through the `IEntitlementProvider`.

### `IEntitlementProvider`: defines which entitlements to attribute

Spring-Security tokens are materialized in ActivePivot as `ISecurityDetails`, which simply
hold a user's roles and username.
An `IEntitlementsProvider` defines which entitlements (i.e. context values) are associated with
each `ISecurityDetails`. For instance, the [mdx context](../mdx/engine_configuration)
can be overridden depending on the users roles, including changes in hierarchy visibility.
`SubCubeProperties` can be used to limit access to certain members of the pivot's
hierarchies depending on the user's roles as well.

You can configure an `IEntitlementsProvider` and attach it to the `ContextValueManager` as follows:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
final IEntitlementsProvider entitlementsProvider =
    EntitlementsProvider.builder()
        .withPivotEntitlement()
        .forRole(ROLE_DESKA_USD)
        .onPivot(PIVOT_ID)
        .withMdxContext()
        .overrideDimensionVisibility(TECHNICAL_DATA_DIMENSION, false)
        .overrideHierarchyVisibility(SIMULATION_DIMENSION, SIMULATION_HIERARCHY_EUR, false)
        .withDefaultMember()
        .onHierarchy(CURRENCY_HIERARCHY)
        .withMemberPath("USD")
        .end()
        .withSubCubeProperties()
        .grantMembers()
        .onHierarchy(DESK_DIMENSION, DESK_HIERARCHY)
        .memberPath("deskA")
        .end()
        .build();
contextValueManager.setEntitlementsProvider(entitlementsProvider);
```

Roles are ordered to be able to choose which context value to set when two roles define the
same context value. The order is defined by an `IAuthorityComparator`.

For example, USER role and ADMIN role may both define a value for the query time limit.
If the ADMIN role is considered of higher authority than the USER role by the
`IAuthorityComparator`, then its value will be used to set the query time limit.

## Sandbox Example

### Entry-point

The sandbox uses Spring-Security, and its security configuration entry point is
`ActivePivotServerSecurityConfig`. This stipulates to use the `ContextValueFilter` class as a filter
at each query start. As explained above, this filter initializes the context values by calling
the `ContextValueManager` provided.

### Defining Entitlements

The sandbox defines its `IEntitlementsProvider` in `RoleContextConfig.entitlementsProvider()`,
and its `IAuthorityComparator` in `ASecurityConfig.authorityComparator()`.

## Advanced topics

By default, `ISecurityDetails` simply holds the username and user roles, but you can generate richer details.
To do so, simply define your own `ISecurityFacade` and
inject it into the `ContextValueManager` using the `setSecurityFacade` method. The sandbox provides
an example through its `SpringSecurityFacade`.