Essencium Backend is a software library built on top of Spring Boot that allows developers to quickly get started on new software projects. Essencium provides, for example, a fully implemented role-rights concept as well as various field-tested solutions for access management and authentication.

java, spring, spring-boot


Essencium Backend

trivy CodeQL Essencium CI - Main Quality Gate Status Reliability Rating

To be used together with:


  • JDK 17
  • Maven >= 3.x
  • PostgreSQL >= 14.x (recommended) or H2 (for development purposes only)

If you are having problems resolving Maven dependencies, check the troubleshooting section.

Project Structure

This repository contains a multi-module Maven project, involving:

  • essencium-backend-parent: Parent module, containing common configuration for all submodules
    • essencium-backend: Base functionality, including user management, authentication, security configuration, i18n, etc. This module is used as a Maven dependency in all newly generated essencium projects.
    • essencium-backend-development: Minimalist example project using essencium-backend-sequence-model as library. Only used for development purposes, i.e. to quickly review and debug changes to the library module.
    • essencium-backend-identity-model: Implementation of essencium-backend using a Long as the primary key following Hibernates identity strategy.
    • essencium-backend-sequence-model: Implementation of essencium-backend using a Long as the primary key following Hibernates sequence strategy.
    • essencium-backend-uuid-model: Implementation of essencium-backend using a Long as the primary key.



  1. Import project in IntelliJ
  2. Install IntelliJ plugins (Settings -> Plugins)
  3. Optional: Start Postgres database using the docker-compose.yml file

Due to the fact that the 'git-pre-commit-hook' currently ignores the integration tests directory for correct formatting of the code, the following command must be executed manually after changes to the integration tests: mvn org.codehaus.mojo:build-helper-maven-plugin:add-test-source@add-integration-test-sources git-code-format:format-code


  1. Run the main class in your IDE or execute mvn spring-boot:run
  2. Access the backend at http://localhost:8098

Initial Data

See here for documentation about initial default data.

Custom User models

See here for documentation on how to extend the default user entity.


See here for extensive documentation about security, authentication and authorization.

Method-level access management & advanced permission checks

See here for extensive documentation and examples on how to restrict certain users from accessing specific entities or entity properties on controller method level.

See here for documentation and examples on how to perform fine-grained access control on controller method level.

JPA Specifications

See here for details on how to write custom JPA Specifications for data querying.

Postman Collection

See here for details on how to use our pre-built Postman collection, containing request examples for all backend endpoints.


See here for details on how to best deploy essencium projects.

Spring Profiles

Different Spring profiles are available to provide default configuration for certain technical aspects.

  • development: A profile to be used during development. Includes debug logging, fake e-mail service, local URLs, etc.
  • h2: A profile for using H2 as a database backend (alternative to postgres, recommended for development purposes)
  • postgres: A profile for using PostgreSQL as a database backend (alternative to h2, recommended in production)
  • ldap: A profile to enable and configure LDAP-based user authentication
  • oauth: A profile to enable and configure OAuth 2 / OpenID Connect-based user authentication

Profiles can be activated by setting SPRING_PROFILES_ACTIVE environment variable (comma-separated values) or in YAML. By default, h2 and development are active. See the section below on how to configure individual properties, including database credentials, OAuth endpoints, etc.

Configuration Options

The following configuration options are available and can be set either in the corresponding application-*.yml config file or as environment variables. This list is not complete, but rather contains the most important variables. Special attention shall be placed on such marked with "⚠️", as these variables are either security-critical or do not have a meaningful default value.

Usually, Essencium-based applications will be deployed as a Docker stack. In this case, it is a good practice to specify all configuration as environment variables inside docker-compose.yml.

YAML Key Environment Variable Default Description
⚠️ - APP_URL http://localhost:8098 in dev profile, undefined otherwise Public base URL of the application (without trailing slash!) SPRING_PROFILES_ACTIVE development,h2 Which Spring profiles to use (recommended for production: production,postgres)
⚠️ MAIL_HOST localhost Mail server hostname
⚠️ mail.port MAIL_PORT 587 Mail server port
⚠️ mail.username MAIL_USERNAME - Mail server username
⚠️ mail.password MAIL_PASSWORD - Mail server password
mail.smtp.start-tls MAIL_SMTP_START_TLS true Whether to use STARTTLS for SMTP server connection
mail.branding.* MAIL_BRANDING_* - Styling / CI for mail templates, see application.yaml for more
sentry.api_url SENTRY_API_URL URL of Sentry instance to use
sentry.organization SENTRY_ORGANIZATION frachtwerk Sentry organization
⚠️ sentry.project SENTRY_PROJECT - Sentry project
⚠️ sentry.token SENTRY_TOKEN - Sentry API token (for forwarding feedback requests) (obtain from at
⚠️ sentry.dsn SENTRY_DSN - Sentry project DSN for error reporting
sentry.enable-tracing SENTRY_ENABLE_TRACING true Whether to log request traces to Sentry's performance monitoring
sentry.traces-sample-rate SENTRY_TRACES_SAMPLE_RATE 0.1 Percentage of requests to trace
app.auth.jwt.expiration APP_AUTH_JWT_EXPIRATION 86400 Validity of issued JWT tokens in seconds
⚠️ app.auth.jwt.secret APP_AUTH_JWT_SECRET - Secret to use for signing JWT tokens
app.cors.allow APP_CORS_ALLOW false Whether to allow CORS requests (all or nothing)
⚠️ spring.datasource.url SPRING_DATASOURCE_URL - Database connection string (see application-h2.yaml and application-postres.yaml for more)
⚠️ spring.datasource.username SPRING_DATASOURCE_USERNAME - Database user
⚠️ spring.datasource.password SPRING_DATASOURCE_PASSWORD - Database password APP_SECURITY_MAX_FAILED_LOGINS 10 Maximum amount of wrong user/password events before the user account is blocked! For LDAP / oAuth Login may a much higher limit than 5 useful.* SPRING_SECURITY_OAUTH2_CLIENT_* - OAuth 2 / OpenID Connection configuration, see application-oauth.yaml and
app.auth.ldap.* APP_AUTH_LDAP_* - LDAP configuration, see application-ldap.yaml
essencium-backend.jpa.table-prefix ESSENCIUM_BACKEND_JPA_TABLE_PREFIX - Defines a prefix for te names of the database tables. FW_ was hardcoded default in previous Starter-Versions. To support databases build on essencium-backend-versions < v2.0.0 FW_ has to be set here.
essencium-backend.jpa.camel-case-to-underscore ESSENCIUM_BACKEND_JPA_CAMEL_CASE_TO_UNDERSCORE - Since Hibernate changed it's default column naming strategy this parameter was introduced to restore the old behavior. Setting this parameter to true hibernates current default is overwritten and default behavior is restored. This is necessary on al deployments that initially used essencium-backend < v2.x.x.



The backend lib comprises both unit- and integration tests.

  • Unit Tests: mvn -f essencium-backend/pom.xml test
  • Integration Tests: mvn -f essencium-backend/pom.xml failsafe:integration-test


Integration Tests are able to send mails through Ethereal. You can log in and see the messages sent using the following credentials:

pass: Du5aaBMb7VEZUjCP9M


Translations can be defined at the time of development using .properties files as seeds as well as during run time via API calls.

Seed Files

This backend lib comes with a set of default translations for German and English, which are defined in essencium-backend/src/main/resources/default_translation/*.properties.

In addition, a user can bring custom, project-specific translations by providing files of the naming scheme * (where xx refers to a certain locale) in the classpath directory src/main/resources/translation of the respective project.

On startup, matching files in this directory are loaded into the database. Project-specific translations take precedence over default translations, i.e. custom translations override default translations with the same key.

Translations, which are present in a seed file, but not in the database are added. However, translations present in the database, which are missing in the seed files, will still not get deleted from the database.


Translations can also be added at runtime via the Admin-UI.

Frachtwerk GmbH