SAML single sign-on for self-hosted AxonOps
Self-hosted AxonOps supports SAML 2.0 single sign-on. With SAML enabled, axon-server authenticates dashboard users against an external identity provider (IdP) and assigns AxonOps roles from the groups the IdP reports for each user. AxonOps holds no passwords and no user records for SAML users; the IdP authenticates each user, and group membership is read from the signed assertion at every sign-in.
- axon-server acts as the SAML service provider (SP). axon-dash serves the dashboard and forwards SAML requests to axon-server.
- Configuration is held in the
authsection of/etc/axonops/axon-server.yml. - Users receive one of four AxonOps roles per scope (all clusters, an organisation, a cluster type, or a single cluster), based on IdP group membership.
- Both SP-initiated sign-in (starting at the AxonOps dashboard) and IdP-initiated sign-in (starting at the IdP's application portal) are supported.
SAML for self-hosted AxonOps has been tested with Microsoft Entra ID, Keycloak, and JumpCloud. Other SAML 2.0 identity providers that meet the requirements on this page are expected to work but have not been tested.
For a step-by-step configuration with Microsoft Entra ID, see SAML single sign-on for self-hosted AxonOps with Microsoft Entra ID.
For AxonOps Cloud, see SAML single sign-on for AxonOps Cloud.
How sign-in works
Section titled “How sign-in works”Four components take part in a SAML sign-in:
- Browser: the user's web browser.
- axon-dash: serves the AxonOps dashboard and proxies requests under
/saml/to axon-server. - axon-server: the SAML service provider. It issues authentication requests, validates assertions, maps groups to roles, and sets the session cookies.
- Identity provider: authenticates the user and issues a signed SAML assertion containing the user's identity and group attributes.
All SAML endpoints are addressed through the dashboard URL (dashboardUrl in the configuration), so the browser and the IdP only ever communicate with axon-dash, never directly with axon-server.
SP-initiated sign-in
Section titled “SP-initiated sign-in”An SP-initiated sign-in starts when an unauthenticated user opens the AxonOps dashboard.
- The browser requests the dashboard without a valid session and is sent to
/saml/login, which axon-dash proxies to axon-server. - axon-server redirects the browser to the IdP with an AuthnRequest, signed with the service certificate and key unless request signing is disabled.
- The IdP authenticates the user according to its own policy.
- The IdP returns a signed assertion, which the browser posts to the Assertion Consumer Service (ACS) URL,
<dashboardUrl>saml/acs, through axon-dash. - axon-server validates the response, sets the session cookies, and redirects the browser to the page originally requested, or to
dashboardUrlwhen no page was recorded.
IdP-initiated sign-in
Section titled “IdP-initiated sign-in”An IdP-initiated sign-in starts at the identity provider, typically when the user selects the AxonOps application in the IdP's application portal. The IdP posts an assertion to the ACS URL without a preceding AuthnRequest. axon-server validates the signature, audience, destination, and validity window in the same way as in the SP-initiated flow, and redirects the browser to dashboardUrl.
IdP-initiated sign-in is always enabled and cannot be disabled in the configuration. Because no AuthnRequest precedes the assertion, axon-server cannot bind the assertion to a request it issued; protection relies on the assertion signature and its short validity window. Where a security policy requires SP-initiated sign-in only, the restriction must be applied at the identity provider, for example by hiding the application from the IdP's application portal.
Prerequisites
Section titled “Prerequisites”- An AxonOps Enterprise licence. In self-hosted deployments, authentication requires an Enterprise licence. Without one, axon-server runs with authentication disabled regardless of the
auth.enabledsetting. See Set up AxonOps License. - A stable dashboard URL. axon-dash must be reachable by users at a fixed URL, for example through a load balancer or reverse proxy. The dashboard should be served over HTTPS only, with plain HTTP redirected or blocked at the proxy: most identity providers require an HTTPS ACS URL, and not every session cookie that axon-server sets carries the
Secureattribute, so transport security must not be left to cookie flags. axon-dash does not terminate TLS itself; see Set up SSL/TLS for AxonOps Dashboard. - An RSA certificate and private key in PEM format for the service provider. A self-signed pair is acceptable. Generation is covered in Create the service certificate and key.
- Administrative access to the identity provider, sufficient to register an application, configure its attributes, and assign groups.
- Permission to edit
/etc/axonops/axon-server.ymland to restart axon-server on the AxonOps server host. - The
org_namevalue fromaxon-server.ymland the names of the clusters that need cluster-level roles, as shown in AxonOps. Both are used in role mapping and are case-sensitive. - A synchronised clock on the axon-server host, for example through NTP. Assertions are rejected when the clocks of the IdP and axon-server differ by more than the tolerance described in Clock skew.
Configure the identity provider
Section titled “Configure the identity provider”Register a new SAML 2.0 application for AxonOps at the identity provider, then supply the values described below. The names of the corresponding fields differ between identity providers.
Create the service certificate and key
Section titled “Create the service certificate and key”axon-server requires an RSA certificate and private key in PEM format, whether or not request signing is enabled. The key must be RSA; EC keys are not supported. The following command generates a self-signed pair valid for 10 years:
openssl req -new -newkey rsa:2048 -sha256 -days 3650 -nodes -x509 \ -subj "/CN=axonops-saml" \ -keyout axonops-saml.key -out axonops-saml.crtRunning the command again overwrites both files with a new key pair. A certificate already registered at the identity provider then no longer matches; see Service certificate rotation.
Copy both files to /etc/axonops on the axon-server host and restrict the private key so that only the axonops user can read it:
sudo cp axonops-saml.crt axonops-saml.key /etc/axonops/sudo chown axonops:axonops /etc/axonops/axonops-saml.crt /etc/axonops/axonops-saml.keysudo chmod 644 /etc/axonops/axonops-saml.crtsudo chmod 600 /etc/axonops/axonops-saml.keysudo -u axonops test -r /etc/axonops/axonops-saml.key && echo "key readable by axonops"The last command prints key readable by axonops on success and nothing on failure. No output indicates that the ownership or permissions are wrong.
The private key is credential material. Any file that axon-server reads for SAML (certificate, key, and IdP metadata) must be readable by the axonops user.
Values to enter at the identity provider
Section titled “Values to enter at the identity provider”| IdP setting | Value |
|---|---|
| Entity ID (also called Identifier or Audience URI) | Any string. Some identity providers require a URL form, such as http://axonops/. The value must equal entityId in axon-server.yml (default axonops). The IdP places it in the assertion's Audience element, which axon-server checks. |
| ACS URL (also called Reply URL or single sign-on URL) | dashboardUrl followed by saml/acs, for example https://axonops.example.com/saml/acs. Binding: HTTP-POST. The binding is the transport the IdP uses to return the assertion; where the IdP offers a choice, HTTP-POST must be selected. |
| SP signing certificate | The contents of axonops-saml.crt, where the IdP verifies signed AuthnRequests. |
| Assertion signing | The IdP must sign the assertion, the response, or both. |
axon-server also publishes SP metadata at <dashboardUrl>saml/metadata, for example https://axonops.example.com/saml/metadata. The metadata contains the entity ID, the ACS URL, and the service certificate for signing and encryption. Identity providers that support SP metadata import can read these values from it once axon-server is running with SAML configured.
Attributes to release
Section titled “Attributes to release”Configure the IdP to include the following attributes in the assertion:
- A unique user identifier.
- A display name.
- An email address or login name.
- A groups attribute listing the groups used for role mapping.
The groups attribute must carry each group as a separate attribute value. A single value containing a comma-separated list of groups does not match any mapping. Note the attribute names exactly as the IdP sends them; see Attribute names.
Download the IdP metadata
Section titled “Download the IdP metadata”Download the IdP's SAML metadata XML, or note its metadata URL. The metadata contains the IdP entity ID, its sign-in endpoint, and its signing certificate. Copy a downloaded file to /etc/axonops, for example as saml_idp_metadata.xml, with the same ownership as the certificate:
sudo cp saml_idp_metadata.xml /etc/axonops/sudo chown root:axonops /etc/axonops/saml_idp_metadata.xmlsudo chmod 640 /etc/axonops/saml_idp_metadata.xmlThe auth configuration
Section titled “The auth configuration”SAML is configured in the auth section of /etc/axonops/axon-server.yml. Take a copy of the file before editing it, so that the previous configuration can be restored quickly:
sudo cp -p /etc/axonops/axon-server.yml /etc/axonops/axon-server.yml.bakConfiguration reference
Section titled “Configuration reference”| Field | Required | Default | Description |
|---|---|---|---|
auth.enabled | Yes | Set to true to enable authentication. | |
auth.type | Yes | Set to "SAML". The value is case-sensitive. | |
settings.idpMetadataFile | One of idpMetadataFile or idpMetadataUrl | IdP metadata XML, as a file path or inline XML. See File paths and inline values. | |
settings.idpMetadataUrl | One of idpMetadataFile or idpMetadataUrl | URL from which axon-server fetches the IdP metadata at startup. | |
settings.entityId | No | axonops | The SP entity ID. The value must match the Entity ID configured at the IdP; the assertion's audience restriction is checked against it. |
settings.serviceCertificate | Yes | SP certificate in PEM format, as a file path or inline PEM. | |
settings.serviceKey | Yes | RSA private key in PEM format, as a file path or inline PEM. | |
settings.requestSigningAlgorithm | No | RSA-SHA256 | Signature algorithm for AuthnRequests: RSA-SHA256, RSA-SHA512, RSA-SHA1, or NONE. Case-insensitive. |
settings.dashboardUrl | Yes | The URL at which users reach axon-dash. See Dashboard URL. | |
settings.groupsAttribute | Yes | Name of the assertion attribute that carries the user's groups. | |
settings.nameAttribute | No | Name of the attribute holding the user's display name. | |
settings.idAttribute | No | Name of the attribute holding the user's unique ID. | |
settings.emailAttribute | No | Name of the attribute holding the user's login or email address. | |
settings.rolesMapping | Yes | Mapping from scopes to IdP group values. See Role mapping. |
In this table settings. refers to auth.settings..
File paths and inline values
Section titled “File paths and inline values”idpMetadataFile, serviceCertificate, and serviceKey each accept either a file path or the content itself:
- A file path may be absolute or relative to
/etc/axonops.axonops-saml.crtrefers to/etc/axonops/axonops-saml.crt. - For
idpMetadataFile, a value containing<is treated as inline XML. - For
serviceCertificateandserviceKey, a value containing a newline,BEGIN CERTIFICATE, orBEGIN PRIVATE KEYis treated as inline PEM.
Inline PEM is written as a YAML block scalar:
serviceCertificate: | -----BEGIN CERTIFICATE----- MIIC... -----END CERTIFICATE-----The service certificate and key sign AuthnRequests and decrypt encrypted assertions. The certificate is also published in the SP metadata.
IdP metadata from a URL
Section titled “IdP metadata from a URL”When idpMetadataUrl is set, axon-server fetches the metadata once at startup, with a timeout of one minute. The metadata is not refreshed while axon-server runs. The axon-server host must be able to reach the URL; a failed fetch prevents axon-server from starting (see Troubleshooting).
This applies to every restart of axon-server, including restarts for upgrades or host maintenance, so idpMetadataUrl makes the availability of the whole AxonOps server depend on the IdP metadata endpoint. idpMetadataFile removes that dependency at the cost of replacing the file manually when the IdP certificate changes. idpMetadataFile should be preferred unless the metadata endpoint is at least as available as axon-server needs to be.
When both idpMetadataFile and idpMetadataUrl are set, axon-server uses idpMetadataFile, ignores idpMetadataUrl, and logs a warning.
Request signing
Section titled “Request signing”With the default requestSigningAlgorithm, axon-server signs every AuthnRequest. Set requestSigningAlgorithm: NONE only when the identity provider cannot verify signed requests. serviceCertificate and serviceKey remain required with NONE.
Dashboard URL
Section titled “Dashboard URL”dashboardUrl is the URL that users enter in the browser to reach axon-dash, including any load balancer or reverse proxy in front of it. axon-server derives the ACS and metadata URLs from it, for example https://axonops.example.com/saml/acs for a dashboardUrl of https://axonops.example.com/.
dashboardUrl should always end with /. Without the trailing slash, the derived URLs are wrong when axon-dash is served under a sub-path.
The Destination of the IdP's response and the Recipient of the assertion must equal the derived ACS URL exactly. A difference in scheme, host name, port, or path causes every sign-in to fail. The ACS URL entered at the IdP must therefore be built from the same dashboardUrl.
User identity attributes
Section titled “User identity attributes”nameAttribute, idAttribute, and emailAttribute determine the display name, unique ID, and login or email that AxonOps records for the session. When one of them is not configured, axon-server substitutes the value of another configured attribute:
| Field | Falls back to (if configured), in order |
|---|---|
| Display name | email, then ID |
| Unique ID | email, then display name |
| ID, then display name |
When none of the three is configured, axon-server uses the SAML NameID (the assertion subject) for all three and logs a warning. When a configured attribute is absent from a particular assertion, axon-server uses the NameID for that field.
Example configuration
Section titled “Example configuration”The following example uses Microsoft Entra ID attribute names. Values are illustrative. The rolesMapping scopes and role keys are explained in Role mapping.
auth: enabled: true type: "SAML" settings: idpMetadataFile: saml_idp_metadata.xml entityId: http://axonops/ serviceCertificate: axonops-saml.crt serviceKey: axonops-saml.key dashboardUrl: https://axonops.example.com/ nameAttribute: http://schemas.microsoft.com/identity/claims/displayname idAttribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress emailAttribute: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress groupsAttribute: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups rolesMapping: _global_: superUserRole: axonops-superusers adminRole: axonops-admins backupAdminRole: axonops-backupadmins readOnlyRole: axonops-readonly my-company/cassandra/prod: superUserRole: "" adminRole: cassandra-prod-admins backupAdminRole: "" readOnlyRole: cassandra-prod-readonlyIn this example, my-company must match the org_name value in axon-server.yml, and prod is the name of a Cassandra cluster as shown in AxonOps.
When configuration changes take effect
Section titled “When configuration changes take effect”axon-server reads axon-server.yml, including the IdP metadata and certificate files, only at startup. Restart axon-server after any change:
sudo systemctl restart axon-serverA SAML configuration error stops axon-server from starting. Errors in this class include a missing required field, an unreadable file, a certificate and key that do not form a valid pair, IdP metadata that cannot be parsed, and an invalid rolesMapping. SAML configuration is read from axon-server.yml only; there are no equivalent environment variables.
Attribute names
Section titled “Attribute names”Each SAML Attribute element in an assertion has a formal Name, often a URI, and may also carry an optional human-readable FriendlyName. axon-server records each attribute under its FriendlyName when the IdP sends one, and under its Name otherwise. The values of groupsAttribute, nameAttribute, idAttribute, and emailAttribute must use whichever of the two the IdP sends.
If a configured attribute name does not exactly match the name the IdP sends, axon-server does not report an error; it treats the attribute as missing from the assertion. For groupsAttribute, this means axon-server sees no groups for any user, so users can sign in but have no access to anything. For nameAttribute, idAttribute, and emailAttribute, axon-server uses the assertion's NameID instead (see User identity attributes).
| Identity provider | Attribute naming |
|---|---|
| Microsoft Entra ID | No FriendlyName is sent, so the full claim URIs are used: display name http://schemas.microsoft.com/identity/claims/displayname, email http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, groups http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. By default Entra ID sends group object IDs (GUIDs), not group names, so rolesMapping values must be the object IDs unless Entra ID is configured to send a different group identifier. See SAML single sign-on for self-hosted AxonOps with Microsoft Entra ID. |
| Keycloak | Each attribute comes from a protocol mapper on the Keycloak client. The configured name is the mapper's Friendly Name when one is set, and its SAML Attribute Name otherwise; both are shown on the mapper's settings page. A common setup uses the role list mapper, which sends the user's roles in an attribute named Role: create Keycloak roles for the AxonOps access levels, assign them to Keycloak groups, set groupsAttribute: Role, and use the role names as the rolesMapping values. |
To see the names and values an IdP sends, inspect a SAML response with the IdP's own diagnostic tools or a browser SAML tracer extension.
Role mapping
Section titled “Role mapping”rolesMapping assigns AxonOps roles to IdP group values, per scope. The four roles are the same as for LDAP authentication:
| Role key | Access |
|---|---|
superUserRole | All operations in AxonOps, including AxonOps settings. |
adminRole | As superUserRole, except configuring AxonOps settings and log collectors. |
backupAdminRole | Creating and managing backups; read-only access to the rest of AxonOps. |
readOnlyRole | Read-only access; cannot modify any configuration. |
Each role key maps to exactly one group value, given as a string, not a list. Matching against the values of groupsAttribute is exact and case-sensitive.
Scopes
Section titled “Scopes”| Scope key | Applies to |
|---|---|
_global_ | All clusters. This scope is required; without it axon-server fails to start with global role mapping required. |
<org_name> | All clusters of the organisation. |
<org_name>/<cluster_type> | All clusters of one type. <cluster_type> is cassandra or kafka. |
<org_name>/<cluster_type>/<cluster_name> | One cluster, named as shown in AxonOps. |
<org_name> is the org_name value in axon-server.yml, set during licence setup. It is case-sensitive, and a scope with a mistyped organisation or cluster name grants nothing.
Every scope must define all four role keys; a scope with a missing key stops axon-server from starting. To leave a role unmapped at a scope, set it to "".
Unrecognised scope keys grant nothing
A scope key that is not one of the forms above, such as a bare cluster name (cluster1:), is accepted at startup but never matches a cluster. Users in the groups mapped under that key receive no access from it, and nothing is logged. Cluster scopes must include the organisation and cluster type, for example my-company/cassandra/cluster1.
Combining groups
Section titled “Combining groups”A user who belongs to several mapped groups receives the highest permission that applies in the current context:
- A user whose groups grant
_global_readOnlyRoleandmy-company/cassandra/cluster1adminRolehas read-only access everywhere except the Cassandra clustercluster1, where the user has admin rights. - A user whose groups grant both
_global_adminRoleand_global_readOnlyRoleis a global admin.
A user who authenticates at the IdP but belongs to no mapped group can sign in and has no access to any cluster.
AxonOps stores no SAML user records, so nothing is provisioned or deprovisioned in AxonOps. Group membership is read from the assertion at each sign-in, and access is managed entirely through group membership at the IdP.
Apply and verify
Section titled “Apply and verify”Once axon-server restarts with SAML enabled, every dashboard user, including the administrator applying the change, must complete a SAML sign-in to use AxonOps. Sessions established before the change are not accepted. Keep a shell session open on the AxonOps server host while verifying, and read Recovery from a broken configuration before restarting.
-
Restart axon-server:
Terminal window sudo systemctl restart axon-server -
Confirm that axon-server is running:
Terminal window systemctl status axon-serverThe output should show
active (running). If axon-server has stopped, check the log for errors (see Troubleshooting). -
Confirm that the SP metadata is served through the dashboard URL and contains the expected entity ID and ACS URL:
Terminal window curl -s https://axonops.example.com/saml/metadata \| grep -oE 'entityID="[^"]*"|Location="[^"]*/saml/acs"'The output should contain the configured
entityIdand the ACS URL registered at the IdP, for example:entityID="http://axonops/"Location="https://axonops.example.com/saml/acs"The ACS line may appear more than once. No output means the metadata was not returned; check that axon-dash is reachable at
dashboardUrland thatauth.typeis"SAML". -
Open
dashboardUrlin a private browser window and confirm that the browser is sent to the IdP sign-in page. Sign in with a test user from each mapped group and confirm the access level, for example that a user mapped only toreadOnlyRolecannot change settings.
Behaviour and limits
Section titled “Behaviour and limits”Sessions
Section titled “Sessions”After a successful sign-in, axon-server issues a SAML session cookie that is valid for one hour. The lifetime is fixed and cannot be configured. When the cookie expires, the next request sends the browser back through the IdP. If the user's IdP session is still valid, the IdP normally completes this without prompting. AxonOps does not otherwise control session lifetime; the IdP's session policy applies.
The groups in the assertion are stored in the session cookie, and rolesMapping is applied to them on each request. As a result:
- Changes to a user's group membership at the IdP take effect at the next sign-in, at most about one hour later. The same applies to a user disabled or removed at the IdP: an existing AxonOps session remains valid until its cookie expires.
- Changes to
rolesMappingtake effect for all signed-in users as soon as axon-server restarts.
The SAML session cookie is signed with the service key. Restarting axon-server does not end SAML sessions, but replacing serviceKey ends all of them.
Logout
Section titled “Logout”SAML single logout is not supported.
Clock skew
Section titled “Clock skew”axon-server checks assertion validity windows with a tolerance of 180 seconds in either direction, and rejects a response or assertion issued more than 90 seconds before axon-server receives it. The clocks of the IdP and the axon-server host must be synchronised.
Encrypted assertions
Section titled “Encrypted assertions”Encrypted assertions are supported. axon-server decrypts them with the service certificate and key.
Metadata and configuration loading
Section titled “Metadata and configuration loading”IdP metadata, whether from idpMetadataFile or idpMetadataUrl, is read only at startup. SAML is configured only through axon-server.yml.
Certificate and metadata rotation
Section titled “Certificate and metadata rotation”IdP signing certificate
Section titled “IdP signing certificate”When the IdP rotates its signing certificate:
- Download the new IdP metadata and replace the metadata file, or, with
idpMetadataUrl, confirm that the URL serves the new metadata. - Restart axon-server.
Between the IdP's switch to the new certificate and the axon-server restart, signature validation fails and no user can sign in. Schedule the restart to follow the IdP change as closely as possible.
Service certificate
Section titled “Service certificate”axon-server holds a single service certificate and key, so replacing them is a cutover with no overlap period. Replacing the key also ends all SAML sessions, and every user signs in again.
- Generate a new pair as described in Create the service certificate and key, in a working directory outside
/etc/axonops. - Replace the certificate and key files in
/etc/axonops, keeping the ownership and permissions described above, and restart axon-server. - If the IdP holds the SP certificate, replace it at the IdP immediately after the restart.
- Repeat the checks in Apply and verify.
Where the IdP verifies signed AuthnRequests or encrypts assertions with the SP certificate, sign-in fails between steps 2 and 3: the IdP rejects requests signed with the new key, or encrypts to the old certificate, which axon-server can no longer decrypt. Where the IdP accepts more than one SP certificate, add the new certificate at the IdP before step 2 and remove the old one after step 4; for an IdP that encrypts assertions, the encryption certificate must still be switched after axon-server has loaded the new key.
Recovery from a broken configuration
Section titled “Recovery from a broken configuration”Most SAML configuration errors stop axon-server from starting, so the dashboard is unavailable rather than open. Check the axon-server log and journalctl -u axon-server for the cause first; correcting the reported error and restarting is usually sufficient.
When axon-server starts but no user can sign in, the only recovery path is to disable authentication.
Disabling authentication opens the dashboard
Setting auth.enabled: false removes authentication for everyone who can reach the dashboard. Any such user can use AxonOps and the clusters it manages without signing in until authentication is enabled again. Restrict network access to axon-dash before disabling authentication.
- Restrict network access to axon-dash, for example with a firewall rule that allows only administrator hosts.
- Set
auth.enabled: falsein/etc/axonops/axon-server.ymland restart axon-server. - Correct the SAML configuration.
- Set
auth.enabled: trueand restart axon-server. - Confirm sign-in works as described in Apply and verify.
- Restore normal network access to axon-dash.
Troubleshooting
Section titled “Troubleshooting”Errors appear in two places:
- Configuration errors at startup are written to the axon-server log (
/var/log/axonops/axon-server.log), and axon-server does not start. - Errors while processing a sign-in, such as an invalid response or assertion, are written by the SAML library to axon-server's standard error. On systemd hosts they appear in
journalctl -u axon-serveras lines beginningWARNING: received invalid saml response:orERROR:. The browser receives an HTTP 403 Forbidden page.
To follow sign-in errors while reproducing a failure:
sudo journalctl -u axon-server -f| Symptom | Message | Cause | Resolution |
|---|---|---|---|
| HTTP 403 after signing in at the IdP | Destination does not match AcsURL or Recipient is not | The ACS URL at the IdP differs from the one derived from dashboardUrl: a missing trailing slash, a different host name or scheme, or a proxy URL that differs from the URL users enter. | Make dashboardUrl the exact URL users enter, ending with /, and set the IdP's ACS URL to <dashboardUrl>saml/acs. Restart axon-server. |
| HTTP 403 after signing in at the IdP | AudienceRestriction does not contain | entityId does not match the Entity ID configured at the IdP. | Set both to the same value and restart axon-server. |
| HTTP 403 after signing in at the IdP | Message containing expired or not yet valid | Clock skew between the IdP and the axon-server host. | Synchronise the axon-server host clock with NTP. |
| HTTP 403 after signing in at the IdP | Signature validation failure | The IdP signing certificate was rotated and axon-server still holds the old metadata, or the IdP does not sign the assertion or response. | Update the IdP metadata and restart axon-server; enable assertion or response signing at the IdP. |
| Sign-in succeeds but the user has no access | None | groupsAttribute does not match the attribute name the IdP sends (FriendlyName rule); group values differ from rolesMapping values, including case; Entra ID sends object IDs while rolesMapping holds group names; the mapping uses a bare cluster name as a scope key; or the IdP sends groups as one comma-separated value. | See Attribute names and Role mapping. Inspect the SAML response to compare the attribute name and values with the configuration. |
| axon-server fails to start | SAML: missing groupsAttribute configuration | groupsAttribute is not set. | Set groupsAttribute. |
| axon-server fails to start | SAML: missing dashboardUrl | dashboardUrl is not set. | Set dashboardUrl. |
| axon-server fails to start | SAML: missing service certificate or SAML: missing service certificate key | serviceCertificate or serviceKey is not set. | Set serviceCertificate and serviceKey. |
| axon-server fails to start | SAML: failed to load certificate or SAML: failed to load certificate key | The certificate or key file does not exist at the configured path or cannot be read by the axonops user. | Check the path (relative paths resolve under /etc/axonops) and the file permissions. |
| axon-server fails to start | SAML: failed to load service certificate | The certificate or key is not valid PEM, or the certificate and key do not belong together. | Configure a matching certificate and key in PEM format, or generate a new pair as described in Create the service certificate and key. |
| axon-server fails to start | SAML: Invalid certificate/key. Only RSA keys are supported | The service key is not an RSA key, for example an EC key. | Generate an RSA key pair as described in Create the service certificate and key. |
| axon-server fails to start | SAML: idpMetadataFile or idpMetadataUrl must be set | Neither metadata setting is present. | Set idpMetadataFile or idpMetadataUrl. |
| axon-server fails to start | SAML: Unable to load IDP metadata | The metadata file does not exist or cannot be read by the axonops user. | Check the path and file permissions. |
| axon-server fails to start | SAML: Failed to fetch metadata from Identity Provider | axon-server cannot retrieve idpMetadataUrl within one minute. | Check network access from the axon-server host to the URL, or use idpMetadataFile. |
| axon-server fails to start | SAML: Unable to parse IDP metadata | The metadata content is not valid SAML metadata. | Download the metadata again from the IdP. |
| axon-server fails to start | SAML: unsupported signing method | requestSigningAlgorithm is not one of the supported values. | Use RSA-SHA256, RSA-SHA512, RSA-SHA1, or NONE. |
| axon-server fails to start | SAML: global role mapping required | rolesMapping has no _global_ scope. | Add a _global_ scope with all four role keys. |
| axon-server fails to start | SAML: invalid adminRole (or the equivalent for another role key) | A scope in rolesMapping is missing a role key. | Define all four role keys in every scope; use "" for unmapped roles. |
| Dashboard opens without sign-in | None | axon-server has no Enterprise licence, so authentication is disabled; or auth.enabled is not true. | Install an Enterprise licence; set auth.enabled: true; restart axon-server. |