> ## 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.

# 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

To use the starter, add the following dependency to your `pom.xml`.

```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<dependency>
  <groupId>com.activeviam.springboot</groupId>
  <artifactId>atoti-server-starter</artifactId>
  <version>${project.version}</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.<br />
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, ...<br />
  *This bean is present only if **one** Datastore exists in the user application.*
* `ActivePivotManager Mbean`: exposes details about the ActivePivotManager - cubes, schemas, performance, ...<br />
  *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.<br />
  *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.<br />
  *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.<br />
  *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](../endpoints/xmla) queries, requests emitted by Excel (or other XMLA client) when interacting with Atoti Server. See [this page](../user_guide/querying/front_ends/excel_xmla) to learn how to connect with Excel.

The interceptor allows to rewrite MDX Select and Drillthrough queries, before being executed by Atoti Server.<br />
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.

<Warning>
  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.
</Warning>

See this [guide](how-to/setup-xmla-interceptor) to learn how to set up an interceptor in an application.

## 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.<br />
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](#roles-and-rights)<br />
The configured authentication is passed to the authorization configuration by the mean of security DSL, described in [this section](#filter-chains-and-dsls). 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.<br />
Admins have every right, and users can only access a limited set of endpoints.<br />
You can set which roles are admins and which are users using the following properties:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
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.<br />
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.<br />
Its default implementation is `AtotiServerHumanDsl`.<br />
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.<br />
Its default implementation is `AtotiServerMachineDsl`.<br />
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.<br />
Its default implementation is `AtotiServerXmlaDsl`.<br />
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.<br />
See an example of XMLA DSL customization [here](../how-to/configure-rest-endpoint-security/#how-to-secure-excel-access-using-dsls).

#### 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`.<br />
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.
  * The key pair can be configured by setting properties `activeviam.jwt.key.public` and `activeviam.jwt.key.private` to the respective key values encoded in Base64.
    Only RSA keys using the PKCS 8 standard are supported.
    Alternatively, a 3072-bit key pair is generated at startup if none was specified.
* 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 `SecurityFilterChain`s 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:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
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.