Skip to main content

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.3-SNAPSHOT</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.

Stock Security​

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