The Atoti Server Starter

Introduction

The Atoti Server Starter is the cornerstone of an Atoti Server application; almost all Atoti projects using starters will use it. Its function is to do setup all the essentials of an Atoti application, such as various services, endpoints and a functional security layer.

Installation

<dependency>
    <groupId>com.activeviam.springboot</groupId>
    <artifactId>atoti-server-starter</artifactId>
    <version>6.1.5</version>
</dependency>

Services setup

The Atoti Server Starter automatically configures quite a few services that used to require manual instantiation, such as all the REST, WS and XMLA services and endpoints, and even some legacy services such as SOAP.
This step of building an Atoti Server application is now handled for you.

Available JMX Beans

The Atoti Server Starter offers out of the box convenient MBeans listed below:

• Datastore MBean: exposes details about the Datastore - schema, indexes, recommendations, ...
  This bean is present only if one Datastore exists in the user application.
• ActivePivotManager Mbean: exposes details about the ActivePivotManager - cubes, schemas, performance, ...
  This bean is present only if one ActivePivotManager exists in the user application.
• Content Service MBean: exposes methods on the service to import/export data, if existing in the user application.
  This bean is present only if a Content Service exists in the user application.
• CSV Source MBean: exposes attributes about defined topics and operations to load data.
  This bean is present only if one CsvSource is defined as a Spring bean in the user application.
• Memory Analysis MBean: exposes methods to import/export memory statistics from the running application.
  This bean is present only if one Datastore or one ActivePivotManager exists in the user application.

Optional Services

XMLA Interceptor

The Atoti Server Starter offers a way to intercept XMLA queries, requests emitted by Excel (or other XMLA client) when interacting with Atoti Server. See this page to learn how to connect with Excel.

The interceptor allows to rewrite MDX Select and Drillthrough queries, before being executed by Atoti Server.
It is also possible to add or update the user context values.

This is often relevant to handle complex queries generated by Excel, incorporating some constructs, like Calculated Members or Context Values on the fly, that require additional configuration that Excel cannot provide.

An interceptor is integrated into Atoti applications by defining a Spring Bean of a dedicated type. Only one such bean can be defined in an application.

caution

When rewriting the underlying MDX query, users must make sure that the transformed MDX query matches the expectations of Excel. Otherwise, the behavior of Excel is undefined.

See this guide to learn how to set up an interceptor in an application.

Stock Security

The Atoti Server Starter focuses on providing a sound authorization configuration out of the box. It does not configure anything related to the authentication, leaving this to projects.
Some predefined roles are baked in the starter. They are used when defining the access rules for endpoints provided by this starter. See more details in this section
The configured authentication is passed to the authorization configuration by the mean of security DSL, described in this section. They do not define any authentication logic on their own.

Projects may keep it as is, alter it using the mechanisms described below, or replace it entirely with a security configuration of their own.

Roles and rights

The default security recognizes two role categories: users and admins.
Admins have every right, and users can only access a limited set of endpoints.
You can set which roles are admins and which are users using the following properties:

atoti:
  server:
    security:
      roles_users:
        - "Role1"
        - "Role2"
      roles_admin:
        - "admin"

If these properties are not set, ROLE_USER is set as the only user role and ROLE_ADMIN as the only admin role.

Filter chains and DSLs

The stock security uses a couple of DSLs that may be extended or overwritten to better suit your needs.
They are intended to be used for both the Atoti Server endpoints and your own endpoints, if any.

Human to Machine DSL

This DSL configures all the endpoints that are intended to be accessed through a browser.
Its default implementation is AtotiServerHumanDsl.
If you wish to change its behavior, you can replace it by exposing a bean of type HumanToMachineSecurityDsl, either by extending our default implementation, or creating your own.

Machine to Machine DSL

This DSL configures all the endpoints that are intended to be accessed through a direct request, such as REST, WS, or GraphQL requests.
Its default implementation is AtotiServerMachineDsl.
If you wish to change its behavior, you can replace it by exposing a bean of type MachineToMachineSecurityDsl, either by extending our default implementation, or creating your own.

XMLA DSL

This DSL configures the XMLA endpoint, which often needs a specific configuration because of Excel's constraints.
Its default implementation is AtotiServerXmlaDsl.
If you wish to change its behavior, you can replace it by exposing a bean of type XmlaSecurityDsl, either by extending our default implementation, or creating your own.

Provided Spring filters

Atoti Server requires several filters, which are passed to the configuration DSLs through a bean implementing the interface com.activeviam.web.spring.api.security.IAtotiServerFilters.
This interface defines the following beans:

• a JWT filter, using the configured key pair to validate bearer tokens. Valid tokens can be generated by any standard JWT service outside of Atoti Server. They are also generated by the Atoti own JWT REST service, provided out of the box by this starter. This service is only accessible through all pre-configured project authentication, automatically excluding JWT itself.
• a filter applying Context Values defined for the logged user to the context of the REST call.

For more extensive changes

If these DSL are not enough to configure the security as wanted by a project, developers may opt to write your own configuration from scratch.

To do so, one will use the properties described in the com.activeviam.springboot.atoti.server.starter.api.PropertyNames class to disable the SecurityFilterChains that a project does not need, allowing to write to new authorization rules to secure the chosen endpoint.

Authentication Flow

A basic authentication flow comes bundled with the starter, adding the /login and /logout endpoints, for logging in and logging out respectively. The login endpoint supports the redirectUrl optional path parameter, which specifies an URL to be redirected to after a successful login.

This flow may be configured with the following properties:

atoti:
  server:
    security:
      login_page:
        form: "file:login_page.html"
        logo: "file:icon.png"
      logout_page:
        form: "file:logout_page.html"
        logo: "file:icon.png"

The form property of each page allows you to specify the entire form used for that page, while the logo property allows you to change the ActiveViam logo to one of your choosing, with only PNG, SVG, and JPEG formats accepted. For more details, see com.activeviam.springboot.atoti.server.starter.api.AtotiSecurityProperties.PageProperties.

You may also want to disable the default authentication flow by using this property: com.activeviam.springboot.atoti.server.starter.api.PropertyNames.AUTHENTICATION_FLOW_ENABLED_PROPERTY

If needed, com.activeviam.springboot.atoti.server.starter.api.LoginLogoutUrls defines as constants the URLs of login/logout and logos.

Websocket configuration

The following properties can be used to configure the websocket engine:

Property	Description	Default value
atoti.server.endpoint.ws.engine.max-idle-timeout	The number of milliseconds before a conversation may be closed by the container if it is inactive, i.e. no messages are either sent or received in that time. Set to 0 to use the default value of the web server.	3600000 (1h)
atoti.server.endpoint.ws.engine.heart-beat-period	The number of milliseconds between heartbeats. Set to 0 so that no heartbeat will ever be sent.	300000 (5min)
atoti.server.endpoint.ws.engine.max-text-message-buffer-size	The maximum length of incoming text messages that the session can buffer. Set to 0 to use the default value of the web server.	8192
atoti.server.endpoint.ws.engine.max-binary-message-buffer-size	The maximum length of incoming binary messages that the session can buffer. Set to 0 to use the default value of the web server.	0