Skip to content

Authentication

Introduction

This documentation provides details on setting up and utilizing the authentication system, which supports multiple authentication methods to cater to different user needs and security requirements.

Supported authentication methods

Production deployment

Please use the LDAP/Auth0/OpenID/SAML strategy for production deployment.

Local users

OpenAEV uses this strategy as the default, but it's not the one we recommend for security reasons.

Parameter Environment variable Default value Description
openaev.auth-local-enable OPENAEV_AUTH-LOCAL-ENABLE true Set this to true to enable username/password authentication.

OpenID

This method allows using the OpenID Connect Protocol to handle the authentication.

Parameter Environment variable Default value Description
openaev.auth-openid-enable OPENAEV_AUTH-OPENID-ENABLE false Set this to true to enable OAuth (OpenID) authentication.

Example for Auth0:

SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_{registrationId}_ISSUER-URI=https://auth.auth0.io
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-NAME=Login with auth0
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-ID=
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT-SECRET=
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_REDIRECT-URI=${openaev.base-url}/login/oauth2/code/{registrationId}
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_SCOPE=openid,profile,email

Example for GitHub (or others pre-handled oauth2 providers):

SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_NAME=Login with Github
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_ID=
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_{registrationId}_CLIENT_SECRET=

Tips

{registrationId} is an arbitrary identifier you choose.

SAML2

This strategy can be used to authenticate your user with your company SAML.

Parameter Environment variable Default value Description
openaev.auth-saml2-enable OPENAEV_AUTH-SAML2-ENABLE false Set this to true to enable SAML2 authentication.

Example for Microsoft : 

SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ENTITY-ID=
SPRING_SECURITY_SAML2_RELYINGPARTY_REGISTRATION_{registrationId}_ASSERTINGPARTY_METADATA-URI=
OPENAEV_PROVIDER_{registrationId}_FIRSTNAME_ATTRIBUTE_KEY=
OPENAEV_PROVIDER_{registrationId}_LASTNAME_ATTRIBUTE_KEY=

Tips

{registrationId} is an arbitrary identifier you choose. metadata-uri is the uri of the xml file given by your identity provider

Single Sign On URL

SAML2

Url for the config of your sso provider 

${openaev.base-url}/login/saml2/sso/{registrationId}

Map administrators to specific roles (OpenID and SAML2)

To grant administrative roles, you can utilize OAuth and SAML2 integration. If you opt for this approach, you'll need to include the following variables:

OPENAEV_PROVIDER_{registrationId}_ROLES_PATH=http://schemas.microsoft.com/ws/2008/06/identity/claims/role
OPENAEV_PROVIDER_{registrationId}_ROLES_ADMIN=

However, if you intend to manage administrative roles within the OpenAEV platform itself, there's no need to provide these variables.

Map users to groups automatically (OpenID and SAML2)

When using OpenID Connect or SAML2, you can automatically assign users to OpenAEV groups at login based on the groups they belong to in your identity provider (IdP). This is controlled by the groups_management parameter.

Parameter Environment variable Description
openaev.provider.{registrationId}.groups_management OPENAEV_PROVIDER_{registrationId}_GROUPS__MANAGEMENT JSON array of group mapping rules (see format below)

Group mapping format

The value must be a JSON array of mapping rules. Each rule maps an IdP group to an OpenAEV group:

[
  {
    "idpGroup": "<group-name-from-your-identity-provider>",
    "userGroup": "<openaev-group-name>",
    "autoCreate": false
  }
]
Field Type Required Description
idpGroup string ✅ The group name as it appears in the IdP token or assertion
userGroup string ✅ The OpenAEV group to assign the user to
autoCreate boolean ✅ If true, the OpenAEV group is created automatically if it does not exist. If false, the mapping is silently skipped when the group does not exist.

Example — Azure AD with SAML2

Map two Azure AD groups to OpenAEV groups:

OPENAEV_PROVIDER_AZURE_GROUPS__MANAGEMENT=[{"idpGroup":"AzureAD-SOC-Team","userGroup":"OpenAEV-SOC","autoCreate":false},{"idpGroup":"AzureAD-Admins","userGroup":"OpenAEV-Administrators","autoCreate":false}]

Or in expanded YAML form:

OPENAEV_PROVIDER_AZURE_GROUPS__MANAGEMENT: |
  [
    {
      "idpGroup": "AzureAD-SOC-Team",
      "userGroup": "OpenAEV-SOC",
      "autoCreate": false
    },
    {
      "idpGroup": "AzureAD-Admins",
      "userGroup": "OpenAEV-Administrators",
      "autoCreate": false
    }
  ]

Group not found behavior

If autoCreate is false and the target OpenAEV group does not exist, the mapping is silently skipped — the user logs in successfully but is not added to the group. Make sure the group names match exactly (case-sensitive).

Breakglass local account with SSO enabled

Why you need a breakglass account

When you configure OpenAEV to use an external identity provider (OpenID Connect or SAML2) as the sole authentication method, your platform becomes dependent on that provider's availability. If the identity provider experiences an outage, a misconfiguration, or a certificate expiry, all users — including administrators — will be locked out of the platform.

A breakglass account (also known as an emergency access account) is a local administrator account that remains available even when SSO is down. It is a critical component of any production deployment that relies on federated authentication.

Security best practice

The breakglass account should only be used in emergency situations when the SSO provider is unavailable. It should not be used for day-to-day operations.

How it works

OpenAEV supports running multiple authentication methods simultaneously. The three authentication flags (Local users, OpenID, SAML2) are independent of each other.

When openaev.auth-local-enable is set to true alongside your SSO provider, the login page will display both the local login form (username/password) and the SSO button(s). This allows the built-in admin account to authenticate locally even if the external identity provider is unreachable.

Configuration

To set up a breakglass account alongside SSO, keep local authentication enabled while configuring your SSO provider.

Step 1: Keep local authentication enabled

Make sure the local authentication flag remains true (this is the default):

OPENAEV_AUTH-LOCAL-ENABLE=true

Step 2: Configure a strong admin account

Set a strong, unique password for the built-in admin account. This is the account defined at platform initialization:

OPENAEV_ADMIN_EMAIL=admin@mycompany.com
OPENAEV_ADMIN_PASSWORD=<a-very-strong-and-unique-password>
OPENAEV_ADMIN_TOKEN=<a-valid-uuidv4-token>

Step 3: Enable your SSO provider

Configure your SSO provider by following the appropriate section:

  • OpenID Connect — for OAuth2/OIDC providers (Auth0, Keycloak, Azure AD, GitHub, etc.)
  • SAML2 — for SAML-based identity providers (Microsoft ADFS, Okta, etc.)

Reminder

Make sure to set OPENAEV_AUTH-OPENID-ENABLE=true or OPENAEV_AUTH-SAML2-ENABLE=true depending on your provider, in addition to the local authentication flag configured in Step 1.

Login page behavior

When both local authentication and an SSO provider are enabled, the login page displays:

  1. The local login form — username and password fields at the top
  2. SSO button(s) — one button per configured OpenID or SAML2 provider below the form

Regular users authenticate via the SSO button. The breakglass admin uses the local form only when the SSO provider is unavailable.