Authentication & OIDC

Connect Eneo to your identity provider using OpenID Connect. These guides help you set up single sign-on for your organization.

Which Setup Do You Need?

One organization, one identity provider.

All users authenticate against the same IdP (Azure Entra ID, Keycloak, Auth0, MobilityGuard, …). Configure it with environment variables or through the sysadmin API.

Single-Tenant

Multiple organizations, each with their own IdP.

Each tenant (municipality, company) uses their own identity provider. Configuration is managed via the sysadmin API - no restarts needed.

Multi-Tenant Federation

Quick Decision Guide

Scenario	Recommended Setup
Single organization deployment	Single-Tenant
Want to change OIDC settings without restarting, or restrict logins by email domain	Single-Tenant via the API
SaaS platform with multiple customers	Multi-Tenant
Each organization brings their own IdP	Multi-Tenant

Supported Identity Providers

Eneo works with any OIDC-compliant identity provider that supports discovery (/.well-known/openid-configuration) and the Authorization Code Flow. Common examples:

Azure Entra ID (formerly Azure AD)
MobilityGuard
Keycloak
Auth0
Okta

The guides walk through Azure Entra ID, Keycloak, Auth0 and MobilityGuard as examples. The same principles apply to other OIDC providers.

Before You Begin

Make sure you have:

Admin access to your Identity Provider
HTTPS enabled on your Eneo domain
Access to the Eneo backend configuration (.env)

For the sysadmin API (single-tenant API setup and multi-tenant):

FEDERATION_ENABLED=true, an ENCRYPTION_KEY and an ENEO_SUPER_API_KEY in the backend .env
Redis (recommended - it caches auth state for tamper detection, but the login flow also works without it)

How OIDC Works with Eneo

Eneo uses the OAuth 2.0 Authorization Code Flow with OpenID Connect:

User opens Eneo and is sent to the login page
Eneo asks the backend for an authorization URL (GET /api/v1/auth/initiate) and redirects to your Identity Provider
User authenticates with their credentials
IdP redirects back to {origin}/login/callback with an authorization code
Eneo exchanges the code for tokens, validates the ID token and matches the user by email
User is logged in

For technical details, see Authentication Architecture. To keep users and groups in sync from your directory, see SCIM Provisioning.

Next Steps

Choose your setup path:

Single-Tenant Setup Multi-Tenant Federation