SAML 2.0 SSO | Axero Documentation

Follow these steps to set up SAML 2.0 Single Sign-On (SSO) on your Axero platform with a third-party identity provider, the service that holds your organization's accounts and checks who is signing in. The steps work with Duo, Shibboleth, IBM Verify, CyberArk, and any other standards-compliant SAML 2.0 provider.

Prerequisites

• Axero intranet site with administrator access
• SAML 2.0 identity provider (such as Duo, Shibboleth, IBM Verify, CyberArk, etc.) with administrative access
• SSL certificate for your Axero domain (HTTPS is required for SAML security)
• Network connectivity between Axero and your SAML provider
• Understanding of your organization's user directory structure and attribute naming conventions

User Login Experience

• Web: Users are sent to your SAML provider to sign in. If the EnableAutoLoginViaSaml system property is set to false, users can choose between SAML SSO and Axero credentials on the login page.
• Mobile App: Users are sent to the SAML provider and sign in through SSO, the same way as on the web.
• Session Management: Session duration is controlled by Axero's authentication settings. When the MakePermanentCookieForThirdPartyLogin system property is set to false, users are signed out when the browser session ends.

Provider Configuration

Important: The exact steps and terms vary a lot by provider, so check your provider's own SAML documentation for detailed instructions. These are the general steps:

1. Create a new SAML application/integration for Axero in your provider's admin console.
2. Set the Assertion Consumer Service (ACS) URL to:
   https://youraxerosite.com/SAML/AssertionConsumerService.aspx
   Replace "youraxerosite.com" with your actual Axero domain.
3. Set the Entity ID (also called Audience URI or SP Entity ID) to your Axero site URL or a unique identifier of your choice.
4. Configure the NameID format. Common options include:
   • Email Address: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
   • Persistent: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
   • Unspecified: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
5. Configure attribute/claim mappings. Attributes (also called claims) are the profile details, such as name and email, that the provider sends when someone signs in. The exact attribute names vary by provider, but commonly include:
   • NameID: User's unique identifier (typically email or username)
   • Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress or email
   • First Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname or givenname
   • Last Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname or surname
   • Additional attributes as needed for your organization
6. Enable SAML Response Signing for security (strongly recommended).
7. Download the IdP metadata XML file or note the SSO/Logout URLs and signing certificate to use when you configure Axero.

Axero Configuration

1. In Axero, go to Control Panel > System > Single Sign On.
2. Select SAML as the SSO type.
3. Click Save.
4. Enter the following information from your SAML provider:
   • Partner Identity Provider URL: The Entity ID from your IdP
   • Single Sign On Service URL: The SSO endpoint URL from your IdP
   • Relying Party Trust Identifier: Your Axero site URL or the Entity ID you configured in your provider
   • Single Logout Service URL: The SLO endpoint URL from your IdP (optional; only if Single Logout is supported by your provider)
   • Partner Identity Certificate (CER): Upload the public signing certificate from your IdP
5. Click Update to save your settings.
6. Click Data Mapping to configure user attribute mapping (see User Data Mapping section below).

Testing Your Configuration

Important: Always test your SAML configuration thoroughly before you roll it out to all users.

1. Test with a single user account:
   • Create or use an existing test user in your SAML provider
   • Make sure the test user has every required attribute filled in
   • Try signing in to Axero using SSO
2. Verify the login flow:
   • Go to your Axero site
   • You should be sent to your SAML provider to sign in
   • After you sign in, you should be sent back to Axero
   • Check that the user's profile details were mapped and appear correctly in Axero
3. Test logout functionality:
   • Log out from Axero
   • If Single Logout (SLO) is configured, verify you are logged out of both Axero and your SAML provider
4. Test error scenarios:
   • Test with a disabled user account
   • Test with a user missing required attributes
   • Check that a clear error message appears

User Management

• Automatic User Creation: By default, Axero creates a user account the first time someone signs in via SAML SSO (if SAMLAutoUserCreation is enabled).
• Pre-Provisioning Users: You can add users in advance using:
  • Bulk Import. Usernames must match the username Axero derives from the NameID. For a user principal name such as jsmith@example.com, Axero stores jsmith, and it strips #EXT# from external guest accounts
  • Control Panel > People > Manage People > Add User
  • REST API for automated provisioning
• Administrator Accounts: Make sure administrator usernames match their SAML user identifiers before you turn on SSO, or update permissions after SSO is set up.
• User Deactivation: Disabling a user in your SAML provider prevents new SSO logins, but the Axero account remains active. To remove access completely, disable or delete the user in Axero yourself.

User Data Mapping

To bring profile details from your SAML provider into Axero, map SAML attributes to Axero properties:

1. Go to Control Panel > System > Single Sign On > Data Mapping.
2. Select SAML as the type.
3. Add attribute mappings. The Property Name must match the exact attribute name sent by your SAML provider in the SAML assertion.

Important Notes:

• Capitalization does not matter for any SAML attribute. Axero compares the name you enter against the names your provider sent while ignoring case, so givenname, givenName, and GIVENNAME all behave the same. The wording does have to match. A name that differs by a word, a space, or a punctuation mark will not be found, and that is the usual cause of a mapping that silently does nothing
• You can enter either the short name or the full claim address, in any capitalization. If you enter a short name such as givenname, Axero also tries it with the standard claim prefix, so it still matches a provider that sends http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• Case sensitivity is different on the SCIM tab. Custom attribute property names there are matched exactly, capitalization included, so a name that works for SAML will not necessarily work for SCIM
• Use the standard SAML claim URIs (the long URLs shown above) where you can, because they work with more providers
• To verify which attributes your provider sends, use browser developer tools to inspect the SAML response during login, or contact your SAML provider administrator for the exact attribute names
• Custom attributes may use simple names (like "department") depending on your provider's configuration

Mapping the manager, or Reports to, field

Send a value that identifies the manager as a person: their email address or their Axero username. A user principal name works too, because Axero falls back to the part before the @ and matches it against usernames. A display name is matched only as a last resort, and unreliably. If nothing else matches, Axero searches for a person whose profile title equals the value exactly. That search depends on the search index being current, and it cannot tell two people with the same name apart, so do not rely on it.

If the value cannot be matched, Axero holds on to it rather than reporting a failure. It resolves the value later if a matching account is created. That is why unmatched managers appear to move into a temporary Reports to value and then fix themselves weeks later.

In Microsoft Entra ID, the claim source you pick decides which of these you get:

Advanced Options

These options are configured in Axero's System Properties:

• SSO Auto Login: EnableAutoLoginViaSaml (default false). Left at false, users see the Axero login page and can choose between Axero credentials and SSO. Set to true, they are redirected straight to your provider. This is also a lockout risk, so know the way back before you set it. With it on, a broken SSO configuration (a site URL that changed after a migration, an unreachable provider, an expired or mismatched certificate) sends everyone, administrators included, into the failure with no way to choose Axero credentials. To recover, set it back to false, which restores the Axero login option. Do that first, before you start reconfiguring SAML. On a self-hosted site where nobody can reach the Control Panel, you can set the value to false directly in the system properties table in the database, then restart the application pool
• Automatic User Creation: SAMLAutoUserCreation (default true) controls whether new users are created automatically on SSO login
• Email Matching: SAMLUserEmailMatch (default false) decides what happens when the incoming username matches an Axero account but the email address does not. Set to true, Axero treats the sign-in as a different person. If automatic user creation is on, Axero creates a second account under a generated username; if it is off, the login fails. The setting does not block the login on its own
• Automatic User Updates: SAMLAutoUserUpdate (default true) controls whether user data is updated from SSO on each login. Because the refresh happens at sign-in, a directory change reaches Axero when the person next signs in and not before. If people stay signed in for weeks, their profiles go stale for weeks. You can shorten that gap with UserInactivityTimeOutInMinutes, which signs people out after a period of inactivity so their next visit starts a fresh SSO sign-in. See System Properties, which also documents MaxInvalidLoginAttempts and FailedAttemptLogInterval for lockout behavior
• Session Persistence: MakePermanentCookieForThirdPartyLogin (default true) determines whether people stay signed in through SSO after they close the browser
• Require a signed response: SAMLWantSAMLResponseSigned (default false when the SSO type is SAML) sets whether Axero requires the SAML response to be signed
• Require a signed assertion: SAMLWantAssertionSigned (default false when the SSO type is SAML) sets whether Axero requires the assertion to be signed
• Role syncing: SCIMSyncRoles (default false) must be on before Axero applies role claims. Turn it on with the Sync roles checkbox on the Data Mapping tab rather than by hand

These properties take the words true or false. A numeric 1 or 0 is not recognized. Most of them then read it as false, so entering 1 for SAMLAutoUserCreation or SAMLAutoUserUpdate turns that setting off rather than on, with no error shown. EnableAutoLoginViaSaml and MakePermanentCookieForThirdPartyLogin are stricter: any value other than the two words raises an error instead of falling back to a value.

The two signing properties are not created on a new site. They appear in System Properties once you select SAML on the Single Sign On page and click Save, which writes both as false. A change to either one takes effect the next time the SAML settings load: when you click Update on the Single Sign On page, or when the site restarts.

Troubleshooting

Common problems when setting up SAML 2.0 SSO with Axero, and how to fix them:

Authentication Issues

Certificate and Security Issues

User Data and Attribute Mapping Issues

User Provisioning and Access Issues

Best Practices

Security Best Practices

• Always use HTTPS: Make sure every address involved uses HTTPS with a valid SSL certificate. SAML 2.0 requires a secure connection for the sign-in messages it carries.
• Enable SAML Response Signing: Configure your SAML provider to sign SAML responses, and make sure Axero checks those signatures.
• Implement least privilege access: Give the service accounts and users involved in SAML sign-in only the permissions they need.
• Minimize attribute exposure: Map only the attributes Axero actually needs. Don't send sensitive or unnecessary personal information.
• Regular access reviews: Check who has access in both your SAML provider and Axero on a regular schedule. Remove accounts for people who no longer need access.
• Secure certificate management: Keep secure backups of certificates and private keys, store them safely, and limit who can open the certificate files.
• Monitor authentication logs: Review your SAML provider's logs and Axero's system logs regularly to spot failed sign-in attempts or configuration problems.

Configuration Management

• Document your configuration: Keep a detailed record of every SSO-related setting, including:
  • SAML provider application configuration and settings
  • Attribute mappings and claim configurations
  • Axero SAML configuration parameters
  • Certificate details and renewal schedules
  • System property values and their purposes
• Version control configuration changes: Before you change anything, back up the working configuration so you can roll back quickly.
• Test in staging first: Always test SSO changes on a non-production site before you apply them to your live site. Test with several user accounts that have different combinations of attributes.
• Plan rollback procedures: Write down how to undo SAML configuration changes quickly if something goes wrong.

Operational Best Practices

• Certificate lifecycle management: Track when certificates expire and plan renewals well in advance. Update certificates in Axero immediately when your SAML provider rotates them.
• Plan for user lifecycle management: Set up processes for:
  • Onboarding new users with appropriate attributes in your SAML provider
  • Updating user information when roles or attributes change
  • Deactivating users when they leave the organization
• Maintain emergency access: Keep another way to sign in, or an emergency administrator account, that doesn't depend on SAML.

Performance and User Experience

• Monitor system performance: Track how long SAML sign-ins take, and look for the steps that slow them down.
• Plan for high availability: Weigh how reliably your SAML provider stays available against how much downtime your organization can accept.
• Implement health checks: Set up monitoring that quickly spots problems with the SAML provider, certificates, or connections.
• Tell people what to expect: Explain the new sign-in path before you switch it on, and tell people who to contact when the provider turns them away. Axero cannot resolve a failure that happens on the provider's side.

Getting Support

If you need help, submit a private case to the Axero support team. Include:

• Detailed description of the issue and steps to reproduce
• Troubleshooting steps you've already attempted
• Error messages and relevant log entries from both Axero and your SAML provider
• Browser and operating system information for affected users
• Screenshots of configuration settings (with sensitive information redacted)
• SAML response content (if available and with sensitive data removed)

With these details, the support team can help you faster and more accurately.

Related pages

• Single Sign-On (SSO) (the provider-specific guides, if yours is listed)
• How to Add an SSO Login Button (to add the SSO button when people can choose either login)
• How to Perform a SAML Trace (to record the sign-in exchange when something fails)
• SHA-256 for Enhanced SSO Security (to confirm your provider signs with SHA-256)
• System Properties (the properties named above)
• ADFS SSO (the ADFS setup)
• Google SSO (the Google setup)
• Auth0 SSO (the Auth0 setup)
• Setup Guide: Entra ID SAML SSO (the same setup, step by step, for Entra ID)