atoti.config package

Module contents

atoti.config.create_aws_config(*, region, client_side_encryption=None)

Create an AWS configuration.

Note

This function requires the atoti-aws plugin.

Parameters

  • client_side_encryption (Union[AwsKeyPair, AwsKmsConfiguration, None]) – The client side encryption mechanism to use when loading data from AWS.

  • region (str) –

    The AWS region to interact with. Required for client side encryption.

    AWS KMS CMK must have been created in the same AWS region as the destination bucket (cf. AWS documentation).

Example

>>> python_config = tt.config.create_config(
...     aws=tt.config.create_aws_config(
...         region="us-east-1",
...     )
... )
>>> yaml_config = '''
... aws:
...   region: us-east-1
... '''
Return type

AwsConfiguration

atoti.config.create_aws_key_pair(*, public_key, private_key)

Create an AWS Key Pair for client side encryption.

Parameters

  • public_key (str) – The public key.

  • private_key (str) – The private key.

Example

>>> python_config = tt.config.create_config(
...     aws=tt.config.create_aws_config(
...         client_side_encryption=tt.config.create_aws_key_pair(
...             public_key="public", private_key="private"
...         ),
...         region="us-east-1",
...     )
... )
>>> yaml_config = '''
... aws:
...   client_side_encryption:
...     key_pair:
...       public_key: public
...       private_key: private
...   region: us-east-1
... '''
Return type

AwsKeyPair

atoti.config.create_aws_kms_config(*, key_id)

Create an AWS KMS configuration for client side encryption.

Parameters

key_id (str) – The key id to identify the key in the KMS.

Example

>>> python_config = tt.config.create_config(
...     aws=tt.config.create_aws_config(
...         client_side_encryption=tt.config.create_aws_kms_config(
...             key_id="abcd1234-12ab"
...         ),
...         region="us-east-1",
...     )
... )
>>> yaml_config = '''
... aws:
...   client_side_encryption:
...     kms:
...       key_id: abcd1234-12ab
...   region: us-east-1
... '''
Return type

AwsKmsConfiguration

atoti.config.create_azure_config(*, client_side_encryption)

Create an Azure configuration.

Note

This function requires the atoti-azure plugin.

Parameters

client_side_encryption (AzureKeyPair) – The client side encryption mechanism to use when loading data from Azure.

Return type

AzureConfiguration

atoti.config.create_azure_key_pair(*, key_id, public_key, private_key)

Create an Azure Key Pair for client side encryption.

Parameters

  • key_id (str) – The id of the key used to encrypt the blob.

  • public_key (str) – The public key.

  • private_key (str) – The private key.

Example

>>> python_config = tt.config.create_config(
...     azure=tt.config.create_azure_config(
...         client_side_encryption=tt.config.create_azure_key_pair(
...             key_id="aaa", public_key="yyy", private_key="xxx"
...         ),
...     )
... )
>>> yaml_config = '''
... azure:
...     client_side_encryption:
...         key_pair:
...             key_id: aaa
...             private_key: xxx
...             public_key: yyy
... '''

Warning

Each encrypted blob must have the metadata attribute unencrypted_content_length with the unencrypted file size. If this is not set, an Issue while downloading error will occur.

Return type

AzureKeyPair

atoti.config.create_basic_authentication(users, *, realm=None)

Create a basic authentication config.

Basic authentication is the easiest way to get started with security since it only requires defining the users, their password, and their roles.

Parameters

  • users (Collection[BasicUser]) – The users that can authenticate against the session.

  • realm (Optional[str]) – The realm describing the protected area. Different realms can be used to isolate sessions running on the same domain (regardless of the port). The realm will also be displayed by the browser when prompting for credentials. Defaults to f"{session_name} atoti session at {session_id}".

Example

>>> python_config = tt.config.create_config(
...     authentication=tt.config.create_basic_authentication(
...         users=[
...             tt.config.create_basic_user(
...                 "admin", "passwd", roles=["ROLE_ADMIN"]
...             ),
...             tt.config.create_basic_user(
...                 "user1", "passwd", roles=["ROLE_FRANCE"]
...             ),
...             tt.config.create_basic_user(
...                 "user2", "passwd", roles=["ROLE_UK"]
...             ),
...         ],
...         realm="Example",
...     )
... )
>>> yaml_config = '''
... authentication:
...   basic:
...     users:
...       - name: admin
...         password: passwd
...         roles:
...           - ROLE_ADMIN
...       - name: user1
...         password: passwd
...         roles:
...           - ROLE_FRANCE
...       - name: user2
...         password: passwd
...         roles:
...           - ROLE_UK
...     realm: Example
... '''
Return type

BasicAuthentication

atoti.config.create_basic_user(name, password, *, roles=None)

Create a basic user with roles.

Parameters

  • name (str) – The username.

  • password (str) – The password of the user.

  • roles (Optional[Collection[str]]) – The roles given to the user. The role ROLE_USER, which is required to access the application, will automatically be added to the passed roles.

Return type

BasicUser

atoti.config.create_branding(*, accent_color=None, favicon=None, frame_color=None, logo=None, title=None)

Create an application branding configuration.

Parameters

  • accent_color (Optional[str]) – The CSS color to give to hovered elements of the frame (header and sidenav).

  • favicon (Union[str, Path, None]) – The file path to the .ico image to use as the favicon.

  • frame_color (Optional[str]) – The CSS color to give to the background of the frame (header and sidenav).

  • logo (Union[str, Path, None]) – The file path to the .svg image that will be displayed in a 24px by 24px area in the upper-left corner.

  • title (Optional[str]) – The title to give to the page.

Example

>>> python_config = tt.config.create_config(
...     branding=tt.config.create_branding(
...         accent_color="#ff00ff",
...         favicon="favicon.ico",
...         frame_color="rgb(42, 42, 42)",
...         logo="../logo.svg",
...         title="Analytic App",
...     )
... )
>>> yaml_config = '''
... branding:
...   accent_color: "#ff00ff"
...   favicon: favicon.ico
...   frame_color: rgb(42, 42, 42)
...   logo: ../logo.svg
...   title: Analytic App
... '''
Return type

Branding

atoti.config.create_config(*, authentication=None, aws=None, azure=None, branding=None, cache_cloud_files=None, default_locale=None, extra_jars=None, https=None, i18n_directory=None, inherit_global_config=True, java_args=None, jwt_key_pair=None, max_memory=None, metadata_db=None, port=None, roles=None, same_site=None, sampling_mode=None, url_pattern=None)

Create a session configuration.

Note

Configuration inheritance is enabled by default. Pass inherit_global_config=False to prevent this configuration from being merged with the global one.

Parameters

  • authentication (Optional[Auth]) –

    Note

    This feature requires Atoti+.

    The authentication mechanism used by the server to configure which users are allowed to connect to the application and which roles they are granted.

  • aws (Optional[AwsConfiguration]) – The atoti-aws configuration.

  • branding (Optional[Branding]) –

    Note

    This feature requires Atoti+.

    The UI elements to change in the app to replace the atoti branding with another one.

  • azure (Optional[AzureConfiguration]) – The atoti-azure configuration.

  • cache_cloud_files (Optional[bool]) –

    Whether to cache loaded cloud files locally in the temp directory. Watched files will not be cached.

    Defaults to True.

    Example

    >>> python_config = tt.config.create_config(cache_cloud_files=False)
>>> yaml_config = '''
... cache_cloud_files: false
... '''

  • default_locale (Optional[str]) –

    Note

    This feature requires Atoti+.

    The default locale to use for internationalizing the session.

    Example

    >>> python_config = tt.config.create_config(default_locale="fr-FR")
>>> yaml_config = '''
... default_locale: fr-FR
... '''

  • extra_jars (Optional[Collection[Union[str, Path]]]) –

    A collection of JAR paths that will be added to the classpath of the Java process.

    Example

    >>> python_config = tt.config.create_config(extra_jars=["../extra.jar"])
>>> yaml_config = '''
... extra_jars:
...   - ../extra.jar
... '''

  • https (Optional[HttpsConfiguration]) –

    Note

    This feature requires Atoti+.

    The certificate and its password used to enable HTTPS on the application.

  • i18n_directory (Union[str, Path, None]) –

    Note

    This feature requires Atoti+.

    The directory from which translation files will be loaded.

    It should contain a list of files named after their corresponding locale (e.g. en-US.json for US translations). The application will behave differently depending on how metadata_db is configured:

    • If metadata_db is a path to a file:

      • If a value is specified for i18n_directory, those files will be uploaded to the local metadata DB, overriding any previously defined translations.

      • If no value is specified for i18n_directory, the default translations for atoti will be uploaded to the local metadata DB.

    • If a remote metadata DB has been configured:

      • If a value is specified for i18n_directory, this data will be pushed to the remote metadata DB, overriding any previously existing values.

      • If no value has been specified for i18n_directory and translations exist in the remote metadata DB, those values will be loaded into the session.

      • If no value has been specified for i18n_directory and no translations exist in the remote metadata DB, the default translations for atoti will be uploaded to the remote metadata DB.

    Example

    >>> python_config = tt.config.create_config(i18n_directory="../i18n")
>>> yaml_config = '''
... i18n_directory: ../i18n
... '''

  • inherit_global_config (bool) –

    Whether this config should be merged with the default config if it exists.

    When working on multiple atoti projects, some configuration properties such as authentication or branding are often wanted to be shared. It is possible to do this sharing without repeating these properties by using configuration inheritance.

    To do so, the shared parts of the configuration can be declared in a global configuration file located at $ATOTI_HOME/config.yml where the $ATOTI_HOME environment variable defaults to $HOME/.atoti.

    Example

    >>> python_config = tt.config.create_config(inherit_global_config=False)
>>> yaml_config = '''
... inherit_global_config: False
... '''

  • java_args (Optional[Collection[str]]) –

    Collection of additional arguments to pass to the Java process (e.g. for optimization or debugging purposes).

    Example

    >>> python_config = tt.config.create_config(
...     java_args=["-verbose:gc", "-Xms1g", "-XX:+UseG1GC"]
... )
>>> yaml_config = '''
... java_args:
...   - -verbose:gc
...   - -Xms1g
...   - -XX:+UseG1GC
... '''

  • jwt_key_pair (Optional[JwtKeyPair]) –

    Note

    This feature requires Atoti+.

    The key pair to use for signing JWT s.

  • max_memory (Optional[str]) –

    Max memory allocated to each session.

    atoti loads all the data in memory of the JVM. This option changes the -Xmx JVM parameter to increase the capacity of the application.

    The format is a string containing a number followed by a unit among G, M and K.

    Defaults to the JVM default memory which is 25% of the machine memory.

    Example

    >>> python_config = tt.config.create_config(max_memory="64G")
>>> yaml_config = '''
... max_memory: 64G
... '''

  • metadata_db (Union[str, Path, None]) –

    The description of the database where the session’s metadata will be stored.

    Metadata is what is not part of the data sources, it includes content such as the dashboards saved by the users in the application.

    If a path to a file is given, it will be created if needed.

    Defaults to None meaning that the metadata is kept in memory and all its content is lost when the atoti session is closed.

    Example

    >>> python_config = tt.config.create_config(metadata_db="../metadata")
>>> yaml_config = '''
... metadata_db: ../metadata
... '''

  • port (Optional[int]) –

    The port on which the session will be exposed.

    Defaults to a random available port.

    Example

    >>> python_config = tt.config.create_config(port=8080)
>>> yaml_config = '''
... port: 8080
... '''

  • roles (Optional[Collection[Role]]) –

    Note

    This feature requires Atoti+.

    Roles restrict what users can see in a cube.

  • same_site (Optional[Literal[‘lax’, ‘none’, ‘strict’]]) –

    Note

    This feature requires Atoti+.

    The value to use for the SameSite attribute of the HTTP cookie sent by the session when authentication is configured.

    Setting it to none requires the session to be served in HTTPS so url_pattern must also be defined and start with https://.

    Defaults to lax.

    Example

    >>> python_config = tt.config.create_config(same_site="strict")
>>> yaml_config = '''
... same_site: strict
... '''

  • sampling_mode (Optional[SamplingMode]) –

    The sampling mode used by default by the store when loading data. It is faster to build the data model when only part of the data is loaded.

    Modes are available in atoti.sampling.

    If not FULL, call load_all_data() to load everything once the model definition is done.

    Defaults to atoti.sampling.first_lines(10000).

    Examples

    • Load all data from the start:

      >>> python_config = tt.config.create_config(
...     sampling_mode=tt.sampling.FULL
... )
>>> yaml_config = '''
... sampling_mode: full
... '''

    • Only load the first 1337 lines:

      >>> python_config = tt.config.create_config(
...     sampling_mode=tt.sampling.first_lines(1337)
... )
>>> yaml_config = '''
... sampling_mode:
...   first_lines: 1337
... '''

    • Only load the first 42 files:

      >>> python_config = tt.config.create_config(
...     sampling_mode=tt.sampling.first_files(42)
... )
>>> yaml_config = '''
... sampling_mode:
...   first_files: 42
... '''

  • url_pattern (Optional[str]) –

    The pattern used to build the URL accessed through atoti.session.Session.url. The following placeholder replacements will be made:

    • {host}: The address of the machine hosting the session.

    • {port}: The port on which the session is exposed.

    • {protocol}: http or https depending on whether the https option was defined or not.

    Defaults to {protocol}://localhost:{port}.

    Example

    >>> python_config = tt.config.create_config(
...     url_pattern="http://{host}:{port}"
... )
>>> yaml_config = '''
... url_pattern: http://{host}:{port}
... '''

Return type

SessionConfiguration

atoti.config.create_https_config(*, certificate, password)

Create a PKCS 12 keystore configuration.

Note

PEM or DER certificates can be converted to PKCS 12 with OpenSSL.

Parameters

  • certificate (Union[str, Path]) – The path to the certificate.

  • password (str) – The password to read the certificate.

Example

>>> python_config = tt.config.create_config(
...     https=tt.config.create_https_config(
...         certificate="../cert.p12", password="changeit"
...     )
... )
>>> yaml_config = '''
... https:
...   certificate: ../cert.p12
...   password: changeit
... '''
Return type

HttpsConfiguration

atoti.config.create_jwt_key_pair(*, public_key, private_key)

Return a key pair to sign JSON Web Tokens.

Atoti+ uses JSON Web Tokens to authenticate communications between its various components (e.g. between the app and the session), but also to authenticate communications with remote metadata DBs. By default, a random key pair of 2048 bytes will be generated at session creation time and used to sign JWTs, but custom RSA key pairs can be set, mainly for SSO purposes.

Only RSA keys using the PKCS 8 standard are supported. A key pair can be generated using a library like pycryptodome for example.

Example

>>> python_config = tt.config.create_config(
...     jwt_key_pair=tt.config.create_jwt_key_pair(
...         public_key="public", private_key="private"
...     )
... )
>>> yaml_config = '''
... jwt_key_pair:
...   public_key: public
...   private_key: private
... '''
Return type

JwtKeyPair

atoti.config.create_kerberos_authentication(*, service_principal, keytab, users, krb5_config=None)

Create a kerberos authentication config.

Atoti+ can be connected to Kerberos authentication network as a service.

Parameters

  • service_principal (str) – The principal the atoti application should use.

  • keytab (Union[Path, str]) – The path to the keytab file to use.

  • users (Collection[KerberosUser]) – The kerberos users.

  • krb5_config (Union[str, Path, None]) – The path to the kerberos config file. Defaults to the default location for the file on .

Example

>>> python_config = tt.config.create_config(
...     authentication=tt.config.create_kerberos_authentication(
...         service_principal="HTTP/localhost",
...         keytab="config/example.keytab",
...         krb5_config="config/example.krb5",
...         users=[
...             tt.config.create_kerberos_user(
...                 name="admin", roles=["ROLE_ADMIN"]
...             ),
...             tt.config.create_kerberos_user(
...                 name="user1", roles=["ROLE_FRANCE"]
...             ),
...             tt.config.create_kerberos_user(name="user2", roles=["ROLE_UK"]),
...         ],
...     )
... )
>>> yaml_config = '''
... authentication:
...   kerberos:
...     service_principal: HTTP/localhost
...     keytab: config/example.keytab
...     krb5_config: config/example.krb5
...     users:
...       - name: admin
...         roles:
...           - ROLE_ADMIN
...       - name: user1
...         roles:
...           - ROLE_FRANCE
...       - name: user2
...         roles:
...           - ROLE_UK
... '''
Return type

KerberosAuthentication

atoti.config.create_kerberos_user(*, name, roles=None)

Create a kerberos user with roles.

Parameters

  • name (str) – The useranme.

  • roles (Optional[Collection[str]]) – The roles given to the user. The role ROLE_USER which is required to access the application, will automatically be added to the passed roles.

Return type

KerberosUser

atoti.config.create_ldap_authentication(*, url, base_dn, user_search_filter='(uid={0})', user_search_base='', group_search_filter='(uniqueMember={0})', group_search_base='', group_role_attribute_name='cn', role_mapping=None)

Create an LDAP authentication config.

Parameters

  • url (str) – The LDAP URL including the protocol and port.

  • base_dn (str) – Base Distinguished Name of the directory service.

  • user_search_filter (str) – The LDAP filter used to search for users. The substituted parameter is the user’s login name.

  • user_search_base (str) – Search base for user searches.

  • group_search_filter (str) – The LDAP filter to search for groups. The substituted parameter is the DN of the user.

  • group_search_base (str) – The search base for group membership searches.

  • group_role_attribute_name (str) – The attribute name that maps a group to a role.

  • role_mapping (Optional[Mapping[str, Collection[str]]]) – The mapping between the roles returned by the LDAP authentication provider and the corresponding roles to use in atoti. LDAP roles are case insensitive. Users without the role ROLE_USER will not have access to the application.

Example

>>> python_config = tt.config.create_config(
...     authentication=tt.config.create_ldap_authentication(
...         url="ldap://example.com:389",
...         base_dn="dc=example,dc=com",
...         user_search_base="ou=people",
...         group_search_base="ou=roles",
...         role_mapping={
...             "admin": ["ROLE_ADMIN"],
...             "france": ["ROLE_FRANCE", "ROLE_EUR"],
...         },
...     )
... )
>>> yaml_config = '''
... authentication:
...   ldap:
...     url: ldap://example.com:389
...     base_dn: dc=example,dc=com
...     user_search_base: ou=people
...     group_search_base: ou=roles
...     name_attribute: email
...     role_mapping:
...       admin:
...         - ROLE_ADMIN
...       france:
...         - ROLE_FRANCE
...         - ROLE_USER
... '''
Return type

LdapAuthentication

atoti.config.create_oidc_authentication(*, provider_id, issuer_url, client_id, client_secret, name_attribute=None, paths_to_authorities=None, scopes=None, role_mapping=None)

Create an OpenID connect authentication config.

Atoti+ is compliant with any OpenID Connect OAuth2 authentication provider (Auth0, Google, Keycloak, etc.).

Parameters

  • provider_id (str) – The name of the provider. This string is used to build the redirectUrl: f"{session.url}/login/oauth2/code/{providerId}".

  • issuer_url (str) – The issuer URL parameter from the provider’s OpenID connect configuration endpoint.

  • client_id (str) – The app’s clientId, obtained from the authentication provider.

  • client_secret (str) – The app’s clientSecret, obtained from the authentication provider.

  • name_attribute (Optional[str]) – The key in the idToken of the parameter to display as the username in the application.

  • paths_to_authorities (Optional[Collection[str]]) – The path to the authorities to use in atoti in the returned access token or id token.

  • scopes (Optional[Collection[str]]) – The scopes to request from the authentication provider.

  • role_mapping (Optional[Mapping[str, Collection[str]]]) – The mapping between the roles returned by the authentication provider and the roles to grant in atoti. Users without the role ROLE_USER will not have access to the application.

Example

>>> python_config = tt.config.create_config(
...     authentication=tt.config.create_oidc_authentication(
...         provider_id="auth0",
...         issuer_url="https://example.auth0.com",
...         client_id="clientId",
...         client_secret="clientSecret",
...         name_attribute="email",
...         scopes=["email", "profile"],
...         paths_to_authorities=["paths/to/authorities"],
...         role_mapping={
...             "dev_team": ["ROLE_USER", "ROLE_DEV"],
...             "admin": ["ROLE_ADMIN"],
...         },
...     )
... )
>>> yaml_config = '''
... authentication:
...   oidc:
...     provider_id: auth0
...     issuer_url: https://example.auth0.com
...     client_id: clientId
...     client_secret: clientSecret
...     name_attribute: email
...     scopes:
...       - email
...       - profile
...     paths_to_authorities:
...       - paths/to/authorities
...     role_mapping:
...       dev_team:
...         - ROLE_USER
...         - ROLE_DEV
...       admin:
...         - ROLE_ADMIN
... '''
Return type

OidcAuthentication

atoti.config.create_role(name, *, restrictions=None)

Create a role with the given restrictions.

  • Restrictions apply on store columns and are inherited by all hierarchies based on these columns.

  • Restrictions on different hierarchies are intersected.

  • However, if a user has several roles with restrictions on the same hierarchies, the access to the union of restricted members will be granted.

There are special roles in atoti that cannot be redefined:

  • ROLE_USER: required to access the application.

  • ROLE_ADMIN: gives full access (read, write, delete, etc…) to the application.

Parameters

Example

>>> python_config = tt.config.create_config(
...     roles=[
...         tt.config.create_role(
...             "ROLE_AMERICA",
...             restrictions={"Country": ["Canada", "USA"]},
...         ),
...         tt.config.create_role(
...             "ROLE_CHINA", restrictions={"Country": "China"}
...         ),
...         tt.config.create_role(
...             "ROLE_FRANCE",
...             restrictions={"Country": "France", "Currency": "Euro"},
...         ),
...     ]
... )
>>> yaml_config = '''
... roles:
...   - name: ROLE_AMERICA
...     restrictions:
...       Country: [Canada, USA]
...   - name: ROLE_CHINA
...     restrictions:
...       Country: China
...   - name: ROLE_FRANCE
...     restrictions:
...       Country: France
...       Currency: Euro
... '''

In this example:

  • A user with the role ROLE_AMERICA will only see the data related to USA and Canada and will not see the data for France.

  • A user with the role ROLE_FRANCE will only see the data where the country is France AND the currency is Euro.

  • A user with both ROLE_AMERICA and ROLE_CHINA will see the data where the country is USA, Canada, OR China.

Return type

Role