# Session configuration¶

When deploying a project, some additional configuration is available. As configuration can depend on where the project is deployed, the configuration can either be defined in YAML files or in Python code through the atoti.config package.

The configuration is passed as an argument of create_session, either as a path to the YAML file or directly as a Python object.

Some data, such as the dashboards generated by the users, is not part of the data sources but is stored anyway in what we call the metadata database. By default, this database is in memory so everything is lost when the Atoti session is closed. However, it can also be persisted to a file.

This is an example of configuration that stores the metadata in a file:

metadata_db: ./metadata.db


which is equivalent to the following Python code:

[1]:

from atoti.config import create_config



## Security¶

Enterprise only: Security is only available in the Enterprise edition of the library.

When sharing your application with other users, you can set up security to configure which users are allowed to connect to the application and which part of the data they are allowed to see.

### Roles¶

Roles are a way to restrict what users can see in a cube. By default, all users mentioned in your configuration file have a role called ROLE_USER which gives access to the full cube. You can define additional roles with restrictions and give these roles to your users.

This in an example of roles in a YAML file:

roles:
- name: ROLE_FRANCE
restrictions:
Country: France
Currency: Euro
- name: ROLE_AMERICA
restrictions:
- name: ROLE_CHINA
restrictions:
Country: [China]


Roles can also be defined directly in Python:

[2]:

from atoti.config import create_config, create_role

french = create_role(
"ROLE_FRANCE", restrictions={"Country": "France", "Currency": "Euro"}
)
american = create_role("ROLE_AMERICA", restrictions={"Country": ["USA", "Canada"]})
chinese = create_role("ROLE_CHINA", restrictions={"Country": "China"})

config = create_config(roles=[french, american, chinese])


Roles are defined per column. Column restrictions are inherited by all hierarchies based on this column. For instance, in the previous configuration, a user with the role ROLE_AMERICA will only see the data related to USA and Canada and won’t see the data for France.

#### Combining roles¶

Restrictions on different hierarchies are intersected. For instance, in the previous configuration, a user with the role ROLE_FRANCE will only see the data where the country is France AND the currency is Euro.

However, if a user has several roles with restrictions on the same hierarchies, the access to the union of restricted members will be granted. For instance, in the previous configuration, a user with both ROLE_AMERICA and ROLE_CHINA will see the data where the country is USA, Canada, OR China.

### Authentication¶

#### Basic¶

Basic handles authentication with usernames and passwords. It is the easiest way to get started with security on a project, you only have to define the users, their password, and their roles.

This is an example of YAML configuration defining 3 users:

authentication:
type: basic
users:
roles:
- name: user1
roles:
- ROLE_FRANCE
- name: user2
roles:
- ROLE_UK


Which is equivalent to the following Python code:

[3]:

from atoti.config import BasicAuthentication, BasicUser, create_config

user1 = BasicUser("user1", "1resu", ["ROLE_FRANCE"])
user2 = BasicUser("user2", "2resu", ["ROLE_UK"])
basic = BasicAuthentication([admin, user1, user2], realm="Configuration Tutorial")

config = create_config(authentication=basic)


#### Auth0¶

Auth0 is an authentication and authorization platform, it can easily be connected to Atoti to handle the authentication.

The configuration requires :

• a role mapping which is a mapping between Auth0 users and Atoti roles

This is an example of YAML configuration for Auth0 giving access to other users:

authentication:
type: auth0
issuer: myIssuer
audience: myAudience
client_id: myClientId
client_secret: myClientSecret
role_mapping:
french_user:
- ROLE_FRANCE


which is equivalent to the following Python code:

[4]:

from atoti.config import Auth0Authentication, create_config

auth0 = Auth0Authentication(
issuer="myIssuer",
audience="myAudience",
client_id="myClientId",
client_secret="myClientSecret",
)


## Properties¶

Properties let you tweak your project to match your special use cases. For instance, the most common property is probably max_memory and you can use it to define how much data your session can hold. All the configurable properties are listed in the atoti.config.Properties enum and can be found in the documentation.

[5]:

from atoti.config import Properties

for prop in Properties:
print(prop)

Properties.csv_max_line_size
Properties.max_memory
Properties.websocket_compression


These properties can be set in YAML:

properties:
max_memory: 64G
websocket_compression: True


which is equivalent to following Python code:

[6]:

from atoti.config import Properties, create_config

config = create_config(
properties={Properties.max_memory: "64G", Properties.websocket_compression: True}
)


## Configuration inheritance¶

Sometimes, you want to use the same base configuration for all your projects. For instance, if you are using the Auth0 account of your company, you won’t want to repeat its properties everywhere. To avoid that, a configuration file can inherit the default configuration file and be merged with it.