Auth0 SSO | Axero Documentation

This guide provides step-by-step instructions for integrating Auth0 Single Sign-On (SSO) with your Axero platform. By following this guide, you will enable secure, seamless SSO for your organization using Auth0 as the identity provider.

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 certificate for SAML token signing (provided by Auth0)

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 log 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. Log 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://yourdomain.communifire.com/SAML/AssertionConsumerService.aspx
     For custom domains: https://yourcustomdomain.com/SAML/AssertionConsumerService.aspx
   • Allowed Logout URLs:
     https://yourdomain.communifire.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://yourdomain.communifire.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 URL (this is your Entity ID)
   • Copy the Identity Provider Login URL
   • Download the Identity Provider Certificate (this will be a .pem or .cer file)

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 Auth0 configuration:
   • Partner Identity Provider URL: Paste the Issuer URL 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://yourdomain.communifire.com)
   • Single Logout Service URL: Leave this field empty or use the same Identity Provider Login URL from Auth0 if your Auth0 configuration supports SLO
   • Partner Identity Certificate (CER): Upload the certificate file you downloaded from Auth0
5. Click Update to save your settings.
6. Click Data Mapping to configure user attribute mapping (see User Data Mapping section).

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 logging into 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 logs in via Auth0 SSO.
• Pre-Provisioning Users: You can add users in advance using:
  • Bulk Import (usernames must match Auth0 identifiers)
  • Control Panel > People > Manage People > Add User
  • REST API for automated provisioning
• Administrator Accounts: If admin accounts are created before SSO setup, ensure usernames match Auth0 user identifiers. Otherwise, update permissions after SSO is enabled.

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. The Property Name should match the attribute name sent by Auth0 in the SAML response.

Common mappings between Auth0 SAML attributes and Axero fields:

Advanced Options

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

• Disable SSO Auto Login: Set EnableAutoLoginViaSaml to false to allow users to choose between Axero and SSO login
• Automatic User Creation: SAMLAutoUserCreation controls if new users are created automatically on SSO login (default: true)
• Email Match: SAMLUserEmailMatch enforces email matching for SSO logins
• Automatic User Update: SAMLAutoUserUpdate controls if user data is updated from SSO on each login (default: true)
• Permanent Cookies: MakePermanentCookieForThirdPartyLogin determines if SSO sessions persist after browser closure

Troubleshooting

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

Authentication Issues

Certificate and Security Issues

User Data and Attribute Mapping Issues

User Provisioning and Access Issues

Auth0-Specific Issues

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, immediately update the corresponding certificate in Axero. Note that Axero may require a restart for certificate changes to take effect.
• 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.
• Communicate changes proactively: Notify users in advance of any SSO-related changes, maintenance windows, or expected downtime.

Performance and Reliability

• 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.
• Capacity planning: Monitor resource usage during peak authentication times and plan for growth in user base.

User Experience

• Provide user training: Educate users about the SSO experience, including what to expect during login and logout processes with Auth0.
• Clear error messaging: Ensure users understand what to do when SAML authentication fails and provide alternative contact methods.
• Browser compatibility guidance: Provide instructions for configuring different browsers for optimal SAML SSO experience.
• Support multiple platforms: Document the authentication experience across different devices and platforms (web, mobile app).

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.