Skip to Content
GuidesAuthentication & OIDC

Authentication & OIDC

Eneo supports OpenID Connect (OIDC) for single sign-on integration with your organization’s identity provider. This guide covers configuration for popular OIDC providers.

Overview

OIDC authentication in Eneo provides:

  • Single sign-on (SSO) for your organization
  • Centralized user management
  • Multi-factor authentication (when supported by your provider)
  • Automatic user provisioning

Configuration

OIDC settings are configured through environment variables in your backend service.

Required Environment Variables

# Enable OIDC authentication
OIDC_ENABLED=true
 
# Your OIDC provider's discovery URL
OIDC_DISCOVERY_URL=https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
 
# Your application's client ID from the OIDC provider
OIDC_CLIENT_ID=your-client-id
 
# Your application's client secret
OIDC_CLIENT_SECRET=your-client-secret
 
# Callback URL where users return after authentication
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback

Azure Entra ID (formerly Azure AD)

Azure Entra ID is Microsoft’s cloud-based identity and access management service.

Step 1: Register an Application

  1. Go to Azure Portal 
  2. Navigate to Azure Active Directory → App registrations
  3. Click New registration
  4. Configure your application:
    • Name: Eneo
    • Supported account types: Accounts in this organizational directory only
    • Redirect URI: Web → https://your-domain.com/api/auth/callback
  5. Click Register

Step 2: Create a Client Secret

  1. In your app registration, go to Certificates & secrets
  2. Click New client secret
  3. Add a description and expiration period
  4. Copy the secret value (you won’t be able to see it again)

Step 3: Configure API Permissions

  1. Go to API permissions
  2. Click Add a permission → Microsoft Graph
  3. Select Delegated permissions
  4. Add these permissions:
    • openid
    • profile
    • email
    • User.Read
  5. Click Grant admin consent (requires admin rights)

Step 4: Configure Eneo

Add these variables to your env_backend.env:

OIDC_ENABLED=true
OIDC_DISCOVERY_URL=https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
OIDC_CLIENT_ID={your-application-id}
OIDC_CLIENT_SECRET={your-client-secret}
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback

Replace:

  • {tenant-id}: Your Azure AD tenant ID (found in Azure AD overview)
  • {your-application-id}: Your app’s Application (client) ID
  • {your-client-secret}: The client secret you created
  • your-domain.com: Your actual domain

Step 5: Restart Eneo

docker compose restart backend

Keycloak

Keycloak is an open-source identity and access management solution.

Step 1: Create a Client

  1. Log in to your Keycloak admin console
  2. Select your realm
  3. Go to Clients → Create client
  4. Configure the client:
    • Client type: OpenID Connect
    • Client ID: eneo
    • Click Next

Step 2: Configure Client Settings

  1. Client authentication: ON (for confidential access type)
  2. Standard flow: Enabled (Authorization Code Flow)
  3. Direct access grants: Disabled
  4. Valid redirect URIs: https://your-domain.com/api/auth/callback
  5. Web origins: https://your-domain.com
  6. Click Save

Step 3: Get Client Secret

  1. Go to the Credentials tab
  2. Copy the Client secret

Step 4: Configure Eneo

Add these variables to your env_backend.env:

OIDC_ENABLED=true
OIDC_DISCOVERY_URL=https://your-keycloak.com/realms/{realm-name}/.well-known/openid-configuration
OIDC_CLIENT_ID=eneo
OIDC_CLIENT_SECRET={your-client-secret}
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback

Replace:

  • your-keycloak.com: Your Keycloak server URL
  • {realm-name}: Your realm name
  • {your-client-secret}: The client secret from step 3

Step 5: Restart Eneo

docker compose restart backend

Auth0

Auth0 is a flexible identity platform.

Step 1: Create an Application

  1. Go to Auth0 Dashboard 
  2. Navigate to Applications → Applications
  3. Click Create Application
  4. Configure:
    • Name: Eneo
    • Application Type: Regular Web Applications
  5. Click Create

Step 2: Configure Application Settings

  1. In the application settings:
    • Allowed Callback URLs: https://your-domain.com/api/auth/callback
    • Allowed Logout URLs: https://your-domain.com
    • Allowed Web Origins: https://your-domain.com
  2. Click Save Changes

Step 3: Get Credentials

From your application’s settings, note:

  • Domain (e.g., your-tenant.auth0.com)
  • Client ID
  • Client Secret

Step 4: Configure Eneo

Add these variables to your env_backend.env:

OIDC_ENABLED=true
OIDC_DISCOVERY_URL=https://your-tenant.auth0.com/.well-known/openid-configuration
OIDC_CLIENT_ID={your-client-id}
OIDC_CLIENT_SECRET={your-client-secret}
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback

Replace:

  • your-tenant.auth0.com: Your Auth0 domain
  • {your-client-id}: Your application’s Client ID
  • {your-client-secret}: Your application’s Client Secret

Step 5: Restart Eneo

docker compose restart backend

Generic OIDC Provider

If your provider isn’t listed above, you can use these general steps:

Requirements

Your OIDC provider must support:

  • OpenID Connect Discovery (.well-known/openid-configuration)
  • Authorization Code Flow
  • Standard OIDC scopes: openid, profile, email

Configuration Steps

  1. Register your application with your OIDC provider

    • Set redirect URI to: https://your-domain.com/api/auth/callback
    • Request scopes: openid, profile, email

  2. Get your credentials:

    • Client ID
    • Client Secret
    • Discovery URL (usually ends with /.well-known/openid-configuration)

  3. Configure Eneo:

    OIDC_ENABLED=true
OIDC_DISCOVERY_URL={your-discovery-url}
OIDC_CLIENT_ID={your-client-id}
OIDC_CLIENT_SECRET={your-client-secret}
OIDC_REDIRECT_URI=https://your-domain.com/api/auth/callback

  4. Restart the backend:

    docker compose restart backend

Testing Your Configuration

After configuration, test the authentication flow:

  1. Navigate to your Eneo instance: https://your-domain.com
  2. You should see a Sign in with SSO button
  3. Click the button and verify you’re redirected to your identity provider
  4. Complete the login process
  5. Verify you’re redirected back to Eneo and logged in

Troubleshooting

Users Can’t Sign In

Check redirect URI configuration:

  • Ensure the redirect URI matches exactly in both your OIDC provider and Eneo configuration
  • Include protocol (https://) and path (/api/auth/callback)

Verify discovery URL:

curl https://your-oidc-provider/.well-known/openid-configuration

This should return a JSON document with OIDC endpoints.

Invalid Client Error

Check client credentials:

  • Verify OIDC_CLIENT_ID matches your provider’s client ID
  • Ensure OIDC_CLIENT_SECRET is correct and hasn’t expired
  • Some providers require secrets to be regenerated periodically

Redirect URI Mismatch

Common causes:

  • HTTP vs HTTPS mismatch
  • Trailing slash differences
  • Port numbers
  • Subdomain differences

Ensure exact match:

  • Provider: https://eneo.example.com/api/auth/callback
  • Eneo: https://eneo.example.com/api/auth/callback

Permission Errors

For Azure Entra ID:

  • Ensure admin consent is granted for required permissions
  • Check the user has access to the application

For Keycloak:

  • Verify the user exists in the correct realm
  • Check client scope mappings

Check Logs

View backend logs for detailed error messages:

docker compose logs backend

Security Best Practices

  1. Use HTTPS: Always use HTTPS in production for redirect URIs
  2. Rotate Secrets: Regularly rotate client secrets
  3. Limit Scopes: Only request the scopes you need
  4. Monitor Access: Review authentication logs regularly
  5. Keep Updated: Keep your OIDC provider configuration current

Need Help?

Last updated on
OverviewAudit Logging