Loading ...

Auth0 SSO | Axero Documentation

Home » axero documentation » Wiki » Documentation » Login » Single Sign-On (SSO) » Auth0 SSO
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 12

Auth0 SSO

0 
 /5
0 (0votes)

This guide provides step-by-step instructions for integrating Auth0 Single Sign-On (SSO) with your Axero platform. Auth0 is the identity provider.

Table of Contents

Prerequisites

Before implementing Auth0 Single Sign-On with your Axero platform, ensure you have the following requirements in place:

System Requirements

  • Axero intranet site with administrator access
    • Access to Control Panel and System configuration settings
    • Ability to configure Single Sign-On settings
  • Auth0 account with administrative privileges
    • Auth0 Dashboard access with application management permissions
    • Ability to create Regular Web Applications
    • Permission to enable and configure SAML2 Web App addons
    • Access to download certificates and view application metadata
  • SSL certificates for both Axero and Auth0
    • HTTPS is required for secure SAML authentication
    • Valid SSL certificate for your Axero domain
    • Certificates must be valid and trusted by client browsers
    • Auth0 signing certificate, which Auth0 provides

Auth0 Environment

  • Auth0 tenant properly configured
    • Active Auth0 subscription with SAML support
    • Auth0 tenant domain accessible via HTTPS
    • Proper DNS resolution for Auth0 endpoints
  • User directory or connection configured in Auth0
    • Database connection, social providers, or enterprise connections
    • User accounts with appropriate attributes populated
    • Connection must support the users who will access Axero

Network and Security Requirements

  • Network connectivity between Auth0 and Axero platform
    • Auth0 services must be accessible from user browsers
    • Firewall rules must allow HTTPS traffic between systems
    • DNS resolution must work properly for all endpoints
  • Access to Auth0 Dashboard and Axero Control Panel
    • Administrative access to configure applications and addons
    • Ability to manage certificates and download metadata
    • Permission to configure callback URLs and application settings

User Login Experience

  • Web: Users are redirected to the Auth0 login page for authentication. Optionally, users can sign in with Axero credentials if EnableAutoLoginViaSaml is set to false in System Properties.
  • Mobile App: Users are redirected to the Auth0 login page and authenticate via SSO, following the same process as the web platform.
  • Session Expiration: Managed by Axero's authentication settings. If MakePermanentCookieForThirdPartyLogin is false, users are logged out when the browser closes.

Auth0 Configuration

  1. Sign in to your Auth0 dashboard as an administrator.
  2. Navigate to Applications in the left sidebar and click Create Application.
  3. Name your application (e.g., "Axero Intranet") and select Regular Web Applications. Click Create.
  4. Go to the Settings tab of your newly created application.
  5. In the Application URIs section, enter the following URLs (replace with your actual domain):
    • Allowed Callback URLs:
      https://intranet.yourcompany.com/SAML/AssertionConsumerService.aspx
      For custom domains: https://yourcustomdomain.com/SAML/AssertionConsumerService.aspx
    • Allowed Logout URLs:
      https://intranet.yourcompany.com/logout
      For custom domains: https://yourcustomdomain.com/logout
  6. Click Save Changes.
  7. Navigate to the Addons tab and enable SAML2 WEB APP.
  8. In the SAML2 addon configuration:
    • Set the Application Callback URL to: https://intranet.yourcompany.com/SAML/AssertionConsumerService.aspx
    • Leave the Settings section with default values unless you need custom attribute mappings
    • Click Enable and then Save
  9. Go to the Usage tab of the SAML2 addon. You will need these values for Axero configuration:
    • Copy the Issuer value, which Auth0 shows as a urn: string (this is your Entity ID)
    • Copy the Identity Provider Login URL
    • Download the Identity Provider Certificate (this will be a .pem or .cer file)
Important: Keep the Issuer, Identity Provider Login URL, and certificate file to hand. You need all three for the Axero configuration step. The Issuer serves as both the Entity ID and the Partner Identity Provider URL in Axero.

Axero Configuration

  1. In Axero, go to Control Panel > System > Single Sign On.
  2. Select SAML as the SSO type.
  3. Note: Saving the authentication method is what resets the signing properties. Choosing SAML and clicking Save writes SAMLWantAssertionSigned and SAMLWantSAMLResponseSigned back to False, so set those two in System Properties only after this step, and set them again if you ever change the method.
  4. Click Save.
  5. Enter the following information from your Auth0 configuration:
    • Partner Identity Provider URL: Paste the Issuer from Auth0 (Entity ID)
    • Single Sign On Service URL: Paste the Identity Provider Login URL from Auth0
    • Relying Party Trust Identifier: Enter your Axero intranet URL (e.g., https://intranet.yourcompany.com)
    • Single Logout Service URL: Leave this empty unless you want signing out of Axero to also sign the person out of Auth0. If you do, this is a different address from the login one. It is https://YOUR_AUTH0_DOMAIN/samlp/YOUR_CLIENT_ID/logout, and it is listed in the Auth0 SAML settings alongside the login URL
    • Partner Identity Certificate (CER): Upload the certificate file you downloaded from Auth0
    • Service Provider Certificate (PFX) and Certificate Password: Needed if you fill in a Single Logout Service URL, because Axero signs its sign-out messages with this certificate. If sign-out does not work after you set a sign-out address, check this certificate first
  6. Click Update to save your settings.
  7. Click Data Mapping to configure user attribute mapping (see User Data Mapping section).
Note: Your SAML settings take effect as soon as you click Update. If sign-in still fails straight afterwards, the cause is the configuration itself rather than a delay, so re-check the three URLs and the certificate against Auth0.

Testing Your Configuration

Before rolling out SSO to all users, test your configuration thoroughly:

Initial Testing Steps

  1. Test with a single user account:
    • Create or use an existing test user in Auth0
    • Ensure the test user has all required attributes populated
    • Try signing in to Axero using SSO
  2. Verify the login flow:
    • Navigate to your Axero site
    • You should be redirected to Auth0 for authentication
    • After successful Auth0 login, you should be redirected back to Axero
    • Check that user data is properly mapped and displayed in Axero
  3. Test logout functionality:
    • Log out from Axero
    • Verify you are properly logged out of both Axero and Auth0

Common Testing Issues

  • Redirect loops: Check that callback URLs match exactly between Auth0 and Axero
  • Certificate errors: Ensure the certificate file is valid and properly uploaded
  • User not created: Verify that SAMLAutoUserCreation is enabled in System Properties

User Management

  • Automatic User Creation: By default, Axero creates a user account the first time someone signs in via Auth0 SSO.
  • Pre-Provisioning Users: You can add users in advance using:
  • Administrator Accounts: If admin accounts are created before SSO setup, make sure the usernames match. Otherwise, update permissions after SSO is enabled.
Matching usernames: Auth0 identifies each person with a single value, and it is often an email address. When that value is an email address, Axero keeps only the part in front of the @ and uses that as the username. Someone identified in Auth0 as jsmith@yourcompany.com becomes jsmith in Axero. If you are creating accounts ahead of time, name them the same way. Creating jsmith@yourcompany.com as the Axero username will not match, and that person gets a second, empty account the first time they sign in.

User Data Mapping

To import user profile data from Auth0 to Axero, map Auth0 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. Type the short name from the table below into the Property Name box, then pick the matching Axero field.

Enter these in the Property Name box, and pick the Axero field beside it:

Property Name to enter in Axero Axero field Notes
givenname First name Sent only when the person's first name is filled in on their Auth0 account. See the note below
surname Last name Sent only when the person's last name is filled in on their Auth0 account. See the note below
emailaddress Email Auth0 sends this as standard
jobtitle Job title Add it in Auth0 first, as described below
department Department Add it in Auth0 first, as described below
telephonenumber Phone Add it in Auth0 first, as described below
city City Add it in Auth0 first, as described below
Enter the short name, not the full address. Auth0 labels each piece of profile information with a long web address, for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname. Type only the last part, givenname, into the Property Name box. Axero fills in the rest. A full address typed in lower case matches nothing, and the field is left empty with no error shown.

Two rules decide whether a Property Name is found:

  • For the fields in the table above, plus company, state and postal code, capitalization does not matter. givenname, givenName and GIVENNAME all work.
  • For any other attribute, type the name in capitals. Axero converts every incoming attribute name to capitals before looking for a match, so a lower case entry that is not one of the fields listed above is not found.

Adding your own attributes. Job title, department, phone and city are not part of what Auth0 sends as standard. To use them, add them in the Auth0 SAML addon settings first. When you do, give the attribute the plain short name (jobtitle, department, telephonenumber, city) and enter that same name in Axero. If you leave the name off in Auth0, it arrives as http://schemas.auth0.com/ followed by the attribute name, which Axero cannot shorten. In that case you have to enter the whole Auth0 address in capitals instead.

First and last name are often empty. Auth0 fills these from the first name and last name held on the person's Auth0 account. For accounts created with an email address and password, those two are frequently blank, so the fields arrive empty and Axero has nothing to store. Check a real account before assuming the names will come across. If they are blank, fill in the first and last name on the Auth0 accounts. Auth0 also sends the person's full name as a single value, so as a fallback you can map it to one Axero field by entering NAME in capitals. Note the capitals: full name is not one of the common fields listed above, so a lower case name will not be found. It also arrives as one piece of text rather than split into first and last.

Auth0 also sends the person's group memberships as standard. To store them on the profile, enter this exact value, in capitals, as the Property Name: HTTP://SCHEMAS.XMLSOAP.ORG/CLAIMS/GROUP. It has to be the whole address in capitals, because this one does not follow the same pattern as the others and Axero cannot shorten it. Mapping it stores the group names on the profile field you choose; it does not assign Axero roles. Roles are set separately on the same Data Mapping tab, by picking a role instead of a profile field.

To see exactly what Auth0 is sending, open the SAML response in your browser's developer tools while signing in, or use a SAML trace tool.

Automatic User Provisioning

The steps above create an Axero account the first time each person signs in. If you would rather have accounts created, updated and deactivated in Axero as soon as they change in Auth0, without waiting for the person to sign in, Axero also supports automatic provisioning.

It is set up on the same page as the settings above, under SCIM User Provisioning at the bottom of Control Panel > System > Single Sign On. Axero generates a bearer token there, which you paste into Auth0 along with the address of your Axero site. SCIM is the industry standard for passing account changes between systems.

Attribute mappings for provisioning are kept separately from the sign-in mappings described above. On the Data Mapping tab, choose SCIM in the Type list rather than SAML, and set the mappings there as well.

Advanced Options

These settings can be configured in Axero's Control Panel > System > System Properties:

  • Disable 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 Auth0
  • Automatic User Creation: SAMLAutoUserCreation controls if new users are created automatically on SSO login (default: true)
  • Email Match: 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: with automatic user creation on it creates a second account under a generated username, and with automatic user creation off the login fails. It does not block the login on its own
  • Automatic User Update: SAMLAutoUserUpdate controls if user data is updated from SSO on each login (default: true)
  • Permanent Cookies: MakePermanentCookieForThirdPartyLogin (default: true) determines if SSO sessions persist after browser closure
  • Require a signed response: SAMLWantSAMLResponseSigned (default: false when the SSO type is SAML). Set to true to have Axero reject a SAML response that is not signed
  • Require a signed assertion: SAMLWantAssertionSigned (default: false when the SSO type is SAML). Set to true to have Axero reject an assertion that is not signed
Before you turn on the signing checks: Auth0 signs the inner part of its sign-in message but not the outer wrapper. Setting SAMLWantAssertionSigned to true works with Auth0 as delivered. Setting SAMLWantSAMLResponseSigned to true will block every sign-in unless you first switch on Sign Response in the Auth0 SAML addon settings. Turn on only one of the two checks: Auth0 signs the response or the assertion, never both, so switching Sign Response on stops it signing the assertion and a site with both Axero checks set to true will still reject every sign-in.

The four SAML properties accept only true or false. Any other value, including a numeric 1 or 0, is read as false. MakePermanentCookieForThirdPartyLogin is stricter still: it is converted rather than parsed, so anything other than true or false raises an error instead of falling back to a value. This matters for the two properties that are on by default: entering 1 for SAMLAutoUserCreation or SAMLAutoUserUpdate switches them off rather than on, and no error is shown. The two signing properties are not present on a new site until you add them under the Single Sign On Settings category.

Troubleshooting

Common issues and their solutions when implementing Auth0 SSO with Axero:

Authentication Issues

Issue Possible Causes Solution
Login fails or users are not redirected to Auth0 SAML SSO not enabled, incorrect Auth0 URLs, misconfigured application settings Verify that SAML SSO is enabled in Axero (Control Panel > System > Single Sign On). Check that all Auth0 URLs (Issuer, SSO URL, Callback URL) are entered correctly in Axero. Verify the Auth0 application is configured properly and that the callback URL matches exactly between Auth0 and Axero.
SSO loop or repeated redirects Mismatched URLs between Auth0 and Axero, browser cache issues, incorrect callback configuration Ensure the Application Callback URL (https://yourdomain/SAML/AssertionConsumerService.aspx) and Logout URLs match exactly between Auth0 and Axero configuration. Clear browser cookies and cache. Verify that the Relying Party Trust identifier is identical in both systems.
"Invalid SAML response" or assertion errors Certificate mismatch, incorrect entity ID, or a signing property turned on that Auth0 is not configured for Check that the Relying Party Trust Identifier matches the value configured in Auth0, and that the certificate uploaded in Axero is the current one from Auth0. Axero does not require a signed message by default, so a signing problem is only the cause here if you have turned on one of the signing properties described under Advanced Options.
"There is no SAML configuration" or similar error SAML not enabled, missing configuration fields, configuration not yet active Check that SAML is enabled in Axero and that every required field is filled in. Verify that the SAML2 Web App addon is enabled in Auth0. Settings apply as soon as you click Update, so if the error persists, submit a support case.
Browser-specific login issues Browser cache, disabled cookies, browser extensions blocking redirects Clear browser cache or try a different browser. Ensure cookies and third-party cookies are enabled. Disable browser extensions that may block redirects.

Certificate and Security Issues

Issue Possible Causes Solution
Certificate errors or invalid certificate Expired certificates, mismatched certificates between Auth0 and Axero, certificate rotation not updated Ensure the uploaded certificate is a valid .cer or .pem file from Auth0 and has not expired. If you rotate certificates in Auth0, upload the new certificate in Axero. The change takes effect as soon as you click Update; no restart is needed.

User Data and Attribute Mapping Issues

Issue Possible Causes Solution
Attribute mapping or user data not syncing Missing attribute configuration in Auth0 SAML addon, the attribute name spelled differently from the Property Name, attributes not included in the assertion Confirm that the Property Name in Axero matches what Auth0 sends. For the common profile fields capitalization does not matter; for any other attribute the Property Name must be typed in capitals. A full claim address typed in lower case never matches. Test with a user who has all required attributes populated in Auth0. Check the Auth0 SAML addon settings for proper attribute mapping.
Email or username changes not reflected User data sync timing, manual update requirements for usernames When a user's email changes in Auth0, Axero updates it on next login if SAMLAutoUserUpdate is enabled. Usernames must be updated manually in Axero if changed in Auth0.

User Provisioning and Access Issues

Issue Possible Causes Solution
New users not being created in Axero User account disabled in Auth0, SAMLAutoUserCreation disabled, username mismatch Ensure the user exists in Auth0 and that SAMLAutoUserCreation is enabled in Axero System Properties, or pre-provision the user in Axero with a matching username.
Disabled users can still access Axero No automatic account deactivation between Auth0 and Axero Disabling a user in Auth0 prevents SSO login, but the Axero account remains active. Delete or ban users in Axero as needed for complete access removal.

Auth0-Specific Issues

Issue Possible Causes Solution
Auth0 SAML Addon not working SAML2 Web App addon not enabled, incorrect callback URL configuration, addon not saved properly Ensure the SAML2 Web App Addon is enabled in Auth0 for your application and configured with the correct callback URL. Verify the addon is active and saved properly.
Auth0 error messages (e.g., "invalid_request", "unauthorized_client") Mismatched application settings, incorrect callback URLs, application configuration errors Check the Auth0 logs in your dashboard for detailed error messages. Verify application settings, callback URLs, and ensure the SAML addon is properly configured.

Best Practices

Security Best Practices

  • Always use HTTPS: Ensure all Axero and Auth0 endpoints use secure HTTPS connections with valid SSL certificates. SAML requires secure transport for security.
  • Implement least privilege access: Only grant necessary permissions to service accounts and user groups involved in SAML authentication.
  • Minimize attribute exposure: Only configure attribute mappings for user data that is actually needed in Axero. Avoid sending sensitive or unnecessary personal information through SAML assertions.
  • Regular access reviews: Periodically audit user access in both Auth0 and Axero. Remove or disable accounts for users who no longer require access. Remember that disabling a user in Auth0 prevents SSO login, but the Axero account remains active.
  • Secure certificate management: Keep secure backups of all certificates and private keys. Use strong encryption for certificate storage and limit access to certificate files.
  • Monitor authentication logs: Regularly review Auth0 logs and Axero system logs to identify failed authentication attempts or configuration issues. Set up alerts for repeated failures or suspicious activity.

Configuration Management

  • Document your configuration: Maintain detailed, secure documentation of all SSO-related settings, including:
    • Auth0 application configuration and SAML addon settings
    • Attribute mappings and claim transformations
    • Axero SAML configuration parameters
    • Certificate details and renewal schedules
    • System property values and their purposes
  • Version control configuration changes: Keep backups of working configurations before making changes to enable quick rollback if needed.
  • Test in staging first: Always validate your SSO configuration in a staging or test environment before deploying to production. Test with multiple user accounts that have different attribute combinations.
  • Plan rollback procedures: Have a documented process to quickly revert SAML configuration changes if issues arise in production.

Operational Best Practices

  • Synchronize server clocks: Configure NTP (Network Time Protocol) on Axero hosting servers to maintain accurate time synchronization. SAML assertions are time-sensitive and will fail with significant clock drift.
  • Certificate lifecycle management: Monitor SSL certificate expiration dates and plan renewals well in advance. When Auth0 rotates certificates, upload the new one in Axero straight away. The change takes effect as soon as you click Update.
  • Plan for user lifecycle management: Establish processes for:
    • Onboarding new users and configuring appropriate attributes in Auth0
    • Updating user information when roles or attributes change
    • Deactivating users when they leave the organization
  • Create emergency access procedures: Maintain alternative authentication methods or emergency administrator accounts that don't depend on Auth0 authentication.

Performance and User Experience

  • Monitor system performance: Track SAML authentication response times and identify potential bottlenecks in the authentication flow.
  • Plan for high availability: Consider Auth0's availability and your organization's requirements for authentication service uptime.
  • Regular health checks: Implement monitoring to detect Auth0 service issues, certificate problems, or network connectivity issues quickly.
  • Tell people what to expect: Explain the new sign-in path before you switch it on, and tell people who to contact when Auth0 turns them away. Axero cannot resolve an Auth0 sign-in failure on its own.

Getting Support

If you encounter issues or need assistance, please submit a private case to the Axero support team. When submitting a support case, include:

  • Detailed description of the issue
  • Steps you've already taken to troubleshoot
  • Error messages from both Axero and Auth0 Dashboard logs
  • Browser and operating system information for affected users
  • Screenshots of configuration settings (with sensitive information redacted)

This information will help the support team provide faster and more accurate assistance.

Wiki Index

Pages