Security

Essencium supports three authentication methods that can be combined as needed:

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

By default, an initial admin user is created with username devnull@frachtwerk.de and password adminAdminAdmin. Roles and rights are always managed in the local database, regardless of which authentication method is used.

Classes

1. WebSecurityConfig: Central Spring Security configuration. Defines which endpoints are protected, registers authentication providers, and sets up the JWT filter chain.

2. JwtTokenAuthenticationFilter: A request filter that reads the JWT from the Authorization: Bearer header or the ?t= query parameter, verifies its signature and session validity via JwtTokenService, and passes the parsed claims downstream.

3. JwtAuthenticationProvider: Receives the pre-validated claims from the filter and builds a UserDetails object from them. Does not perform signature verification or session checks — that responsibility belongs to JwtTokenAuthenticationFilter.

4. DaoAuthenticationProvider: Handles local username/password logins by loading the user from the database and verifying the password hash.

5. LdapAuthenticationProvider: Handles LDAP logins. Binds to the LDAP server with the user’s credentials and maps LDAP group memberships to application roles.

6. OAuth2LoginAuthenticationProvider: Handles the OAuth 2 / OpenID Connect login flow, configured via http.oauth2Login(...) in WebSecurityConfig. After a successful redirect from the external provider, the user is looked up or created in the local database.

Password Strength

Local password strength is enforced via the zxcvbn library. The required strength level (1–4) is configured with app.security.min-password-strength; the default is 3. See the zxcvbn demo to understand how passwords are scored, and this article for the underlying approach.

JWT Tokens

Once a login succeeds, the system issues two tokens: a short-lived access token and a long-lived refresh token. Both are JWTs. Session tokens are stored server-side and looked up by their kid (key ID) claim on each request. Token lifetimes are configured with:

• app.auth.jwt.access-token-expiration (default: 900 seconds / 15 minutes)
• app.auth.jwt.refresh-token-expiration (default: 2592000 seconds / 30 days)

Token Invalidation

Because session tokens are stored server-side, they can be explicitly revoked. Calling POST /v1/users/{id}/terminate deletes all stored session tokens for that user via JwtTokenService, immediately invalidating all active access and refresh tokens.

See the Authentication Guide for the API call details.

For configuration instructions, see the Authentication Guide.