Authentication

Essencium supports three authentication methods:

Local user database (username / password login) — always active
External LDAP directory (username / password login) — optional
External OAuth 2 provider (OpenID Connect flow) — optional

For an explanation of how each method works internally, see Security.

Configure LDAP

To enable LDAP login, activate the ldap Spring profile and configure the following variables in application-ldap.yaml:

Environment Variable	Example	Description
APP_AUTH_LDAP_ENABLED	`true`	Enables LDAP login
APP_AUTH_LDAP_ALLOW_SIGNUP	`true`	Automatically creates a user account on the first successful login
APP_AUTH_LDAP_URL	`ldap://ldap.admin.frachtwerk.de:389/dc=user,dc=frachtwerk,dc=de`	LDAP URL including base path
APP_AUTH_LDAP_USER_SEARCH_BASE	`ou=users`	Sub-path in which all users must be located
APP_AUTH_LDAP_USER_SEARCH_FILTER	`(mail={0})`	Filter used to look up users
APP_AUTH_LDAP_MANAGER_DN	`uid=service.fwfin,ou=services,ou=users,dc=user,dc=frachtwerk,dc=de`	BindDN account used to connect to the LDAP server
APP_AUTH_LDAP_MANAGER_PASSWORD	`secret`	Password for the BindDN account
APP_AUTH_LDAP_USER_FIRSTNAME_ATTR	`givenName`	LDAP attribute containing the user’s first name
APP_AUTH_LDAP_USER_LASTNAME_ATTR	`sn`	LDAP attribute containing the user’s last name
APP_AUTH_LDAP_USER_UPDATE_ROLE	`true`	Assigns application roles automatically on each login based on the first matching role mapping
APP_AUTH_LDAP_USER_ROLE_ATTR	`memberOf`	LDAP attribute containing group membership
APP_AUTH_LDAP_ROLES_0_SRC	`cn=freelancer,ou=groups,dc=user,dc=frachtwerk,dc=de`	LDAP group for role mapping 0
APP_AUTH_LDAP_ROLES_0_DST	`FREELANCER`	Application role for role mapping 0
APP_AUTH_LDAP_ROLES_1_SRC	`cn=admin-fwfin,ou=groups,dc=user,dc=frachtwerk,dc=de`	LDAP group for role mapping 1
APP_AUTH_LDAP_ROLES_1_DST	`ADMIN`	Application role for role mapping 1

Configure OAuth 2

Activate the OAuth 2 login by setting app.auth.oauth.enabled to true.
(Optional) Set app.auth.oauth.allow-signup to true to automatically create a new user account on the first successful login via an external provider.
Configure your OAuth provider using the spring.security.oauth2.client.* properties.

Here is an example configuration for application-oauth.yaml after activating the OAuth-Profile in application.yaml:

spring:
  security:
    oauth2:
      client:
        registration:
          fwoidc:
            client-id: frachtwerk-essencium-demo
            client-name: Frachtwerk Essencium App
            client-secret: sshhh
            scope: openid
            redirect-uri: http://localhost:8098/login/oauth2/code/fwoidc
            provider: fwoidc
            client-authentication-method: basic
            authorization-grant-type: authorization_code
 
        provider:
          fwoidc:
            authorization-uri: https://login.example.org/auth/realms/essencium/protocol/openid-connect/auth
            token-uri: https://login.example.org/auth/realms/essencium/protocol/openid-connect/token
            user-info-uri: https://login.example.org/auth/realms/essencium/protocol/openid-connect/userinfo
            jwk-set-uri: https://login.example.org/auth/realms/essencium/protocol/openid-connect/certs
            user-name-attribute: email
            user-info-authentication-method: header

Logging In

Username & password (local or LDAP)

Send a POST request to /auth/token with a JSON body:

{ "username": "your_user@example.com", "password": "your_password" }

On success, the response contains a JWT token:

{ "token": "<TOKEN_HERE>" }

OAuth 2

Given a configured provider named fwoidc:

Open http://localhost:8098/oauth2/authorization/fwoidc in your browser — this redirects to the external authorization server.
After successful login, you are redirected back to /?token=<TOKEN_HERE>. Copy the token from the URL query parameter.

Making Authenticated Requests

Include the JWT token in every API request (all routes under /v1/** require authentication) using either:

The Authorization header: Authorization: Bearer <TOKEN_HERE>
A query parameter: ?t=<TOKEN_HERE>

To get a new access token using your refresh token, call POST /auth/renew. This endpoint requires both:

The refreshToken cookie (set automatically after login)
The Authorization: Bearer <ACCESS_TOKEN> header (the current, possibly expired access token)

Invalidating a User’s Sessions

To immediately invalidate all active tokens for a user (for example, after a suspected account compromise), call:

POST /v1/users/{id}/terminate

This endpoint requires the USER_UPDATE right. It deletes all stored session tokens for that user, immediately invalidating all active access and refresh tokens. For details on how this mechanism works, see Security.

Setup Dependencies