OAuth2 Authentication

Axon Server supports OAuth2 integration for authentication. User accounts and roles from the OAuth provider are not synchronized to the Axon Server cluster. This means an account needs to be created in the cluster with the username from the provider, and roles assigned.

OAuth2 support was a separately installed extension prior to Axon Server 2026.0. It is now part of the core product and requires no additional installation.

Configuration

  • axoniq.axonserver.accesscontrol.enabled

This must be set to “true” to enable access control.

  • axoniq.axonserver.enterprise.oauth2.enabled

This must be set to “true” to enable OAuth2 authentication.

  • axoniq.axonserver.enterprise.oauth2.mode

Set this value to “google” for Google Apps authentication, or “oidc” to use the generic OpenID Connect integration. The OpenID Connect integration is known to work with KeyCloak server.

Google Apps authentication

For authentication using Google Apps accounts, use the following properties:

  • axoniq.axonserver.enterprise.oauth2.authorization-uri

This optional value can be used to configure the URI that will trigger the authentication using OAuth2. The default value is “/oauth2/authorization” and should work fine.

  • spring.security.oauth2.client.registration.google.client-id

This should be set to the client-id provided by the Google Developer Console where you registered the cluster.

  • spring.security.oauth2.client.registration.google.client-secret

This should be set to the secret provided by the Google Developer Console where you registered the cluster.

  • spring.security.oauth2.client.registration.google.scope

This setting is used to configure what information Google should share with the Axon Server cluster. A good value to use is “email”, which will allow you to use the email address as username, as is common with Google accounts.

  • axoniq.axonserver.enterprise.oauth2.username-map.google

Controls what value to use as username. Requires that this value is provided by Google using the “scope” setting described above. If the email address is to be used, as suggested above, the value should be “email”.

  • axoniq.axonserver.enterprise.oauth2.request-params

This setting defines a map of parameters to add to the redirect URL, to customize the behavior of the provider’s integration. For Google, if the users use the same browser with multiple Google accounts, a good setting to add is “prompt”, with value “select_account”:

`properties axoniq.axonserver.enterprise.oauth2.request-params.prompt=select_account `

This will force Google to always ask which account must be used to continue, even if there is only a single account in use, and that account is currently active.

OpenID Connect authentication with KeyCloak

For authentication using KeyCloak, you need to configure a realm and, in it, configure Axon Server as a client. You can use the following properties:

  • axoniq.axonserver.enterprise.oauth2.forceOidcLogout

Setting this property to “true” will ensure that, when the user logs out from the Axon Server UI, a logout request will also be sent to KeyCloak. If set to “false” (the default), the user will still have a valid session in KeyCloak, and a subsequent login attempt using the same browser window may immediately succeed, without a prompt for a password. Naturally this is dependent on session validity settings within KeyCloak.

  • spring.security.oauth2.client.registration.oidcclient.client-id

This should be set to the client ID configured for Axon Server.

  • spring.security.oauth2.client.registration.oidcclient.client-secret

This should be set to the client secret configured for Axon Server.

  • spring.security.oauth2.client.registration.oidcclient.client-name

This should be set to the client name configured for Axon Server.

  • spring.security.oauth2.client.registration.oidcclient.provider

This should be set to the value “keycloak”.

  • spring.security.oauth2.client.registration.oidcclient.scope

This should be set to a (comma separated) list of the information that needs to be shared, typically “openid,email,profile”.

  • spring.security.oauth2.client.provider.keycloak.issuer-uri

This should be set to the realm’s URL on KeyCloak. For example, if the realm is named “test-realm” and KeyCloak is exposed at “http://keycloak-test:8090”;, then the value is “http://keycloak-test:8090/realms/test-realm”;.

  • axoniq.axonserver.enterprise.oauth2.username-map.oidcclient

Controls what value to use as username. The suggested value is “username”, which refers to that value from the “profile” scope. Alternatively, just as with the Google Apps integration mentioned above, you can use “email”.

  • axoniq.axonserver.enterprise.oauth2.auto-redirect

Toggle automatic redirects to the IDP. This will cause AxonServer to skip the login page of AxonServer and users won’t be able to choose a login mechanism. This setting does not disable logins via password though. Only one authentication provider may specify automatic redirects.

Configuring user access and roles

If a username is unknown in the Axon Server cluster, even when authentication succeeds, the user will not be allowed to log in. To allow this, a user with “ADMIN” level access needs to create a user, optionally without a password, and assign the roles for this user. The Axon Server CLI has a special option (“--no-password”) to allow the creation of accounts without a password. Note that if you create an account with a password, this will allow the user to choose to use that as well as the OAuth2 integration.