SAML 2.0 SSO | Axero Documentation

This guide provides step-by-step instructions for integrating SAML 2.0 Single Sign-On (SSO) with your Axero platform using third-party identity providers such as Duo, Shibboleth, IBM Verify, CyberArk, and others. By following this guide, you will enable secure, seamless SSO for your organization using any 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 redirected to your SAML provider for authentication. 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 redirected to the SAML provider and authenticate via SSO, following the same process as the web platform.
• Session Management: Session duration is controlled by Axero's authentication settings. When the MakePermanentCookieForThirdPartyLogin system property is set to false, users are logged out when the browser session ends.

Provider Configuration

Important: The exact steps and terminology vary significantly by provider. Consult your provider's specific SAML documentation for detailed instructions. The following are general configuration 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. The specific 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 for use in Axero configuration.

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 deploying to all users.

1. Test with a single user account:
   • Create or use an existing test user in your SAML provider
   • Ensure the test user has all required attributes populated
   • Attempt to log into Axero using SSO
2. Verify the login flow:
   • Navigate to your Axero site
   • You should be redirected to your SAML provider for authentication
   • After successful authentication, you should be redirected back to Axero
   • Verify that user data is properly mapped and displayed 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
   • Verify appropriate error messages are displayed

User Management

• Automatic User Creation: By default, Axero creates a user account the first time someone logs in via SAML SSO (if SAMLAutoUserCreation is enabled).
• Pre-Provisioning Users: You can add users in advance using:
  • Bulk Import (usernames must match SAML NameID values)
  • Control Panel > People > Manage People > Add User
  • REST API for automated provisioning
• Administrator Accounts: Ensure admin account usernames match SAML user identifiers before enabling SSO, or update permissions after SSO is configured.
• User Deactivation: Disabling a user in your SAML provider prevents new SSO logins, but the Axero account remains active. You must manually disable or delete users in Axero for complete access removal.

User Data Mapping

To import user profile data from your SAML provider to Axero, you need to 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:

• Attribute names are case-sensitive and must match exactly as sent by your SAML provider
• Standard SAML claim URIs (the long URLs shown above) are recommended for better interoperability
• 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

Advanced Options

These options are configured in Axero's System Properties:

• Disable SSO Auto Login: Set EnableAutoLoginViaSaml to false to allow users to choose between Axero and SSO login on the login page
• Automatic User Creation: SAMLAutoUserCreation controls whether new users are created automatically on SSO login
• Email Matching: SAMLUserEmailMatch enforces email address matching for SSO logins
• Automatic User Updates: SAMLAutoUserUpdate controls whether user data is updated from SSO on each login
• Session Persistence: MakePermanentCookieForThirdPartyLogin determines whether SSO sessions persist after browser closure

Troubleshooting

Common issues and solutions when implementing SAML 2.0 SSO with Axero:

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: Ensure all endpoints use secure HTTPS connections with valid SSL certificates. SAML 2.0 requires secure transport for security assertions.
• Enable SAML Response Signing: Configure your SAML provider to sign SAML responses and ensure Axero validates these signatures.
• Implement least privilege access: Grant only necessary permissions to service accounts and users involved in SAML authentication.
• Minimize attribute exposure: Only configure attribute mappings for data actually needed in Axero. Avoid transmitting sensitive or unnecessary personal information.
• Regular access reviews: Periodically audit user access in both your SAML provider and Axero. Remove accounts for users who no longer require access.
• Secure certificate management: Maintain secure backups of certificates and private keys. Use proper certificate storage practices and limit access to certificate files.
• Monitor authentication logs: Review SAML provider logs and Axero system logs regularly to identify failed authentication attempts or configuration issues.

Configuration Management

• Document your configuration: Maintain detailed documentation of all SSO-related settings, 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: Keep backups of working configurations before making changes to enable quick rollback.
• Test in staging first: Always validate SSO configuration in a non-production environment before deploying to production. Test with multiple user accounts having different attribute combinations.
• Plan rollback procedures: Document processes to quickly revert SAML configuration changes if issues arise.

Operational Best Practices

• Certificate lifecycle management: Monitor certificate expiration dates and plan renewals well in advance. Update certificates in Axero immediately when your SAML provider rotates them.
• Plan for user lifecycle management: Establish 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 alternative authentication methods or emergency administrator accounts that don't depend on SAML authentication.
• Communicate changes proactively: Notify users in advance of SSO-related changes, maintenance windows, or expected downtime.

Performance and Reliability

• Monitor system performance: Track SAML authentication response times and identify potential bottlenecks.
• Plan for high availability: Consider your SAML provider's availability and your organization's uptime requirements.
• Implement health checks: Set up monitoring to detect SAML provider issues, certificate problems, or connectivity issues quickly.
• Capacity planning: Monitor resource usage during peak authentication times and plan for user base growth.

User Experience

• Provide user training: Educate users about the SSO experience, including login and logout processes.
• 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 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)

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