ADFS SSO | Axero Documentation

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

Prerequisites

Before implementing Microsoft ADFS 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
• Microsoft Active Directory and ADFS 3.0 or later installed and configured
  • ADFS service must be running and functional
  • Access to ADFS Management Console
  • ADFS metadata must be accessible via HTTPS
  • Note: ADFS 2.0 is supported but some configuration steps may differ
• SSL certificates for both Axero and ADFS
  • HTTPS is required for secure SAML authentication
  • Certificates must be valid and trusted by client browsers
  • Token-signing certificate from ADFS for Axero configuration

Active Directory Environment

• Microsoft Active Directory environment with domain controller access
  • Active Directory Domain Services (AD DS) installed and running
  • Domain controllers accessible from the ADFS server
  • Time synchronization between all servers is critical for SAML authentication
• Domain administrator privileges or equivalent permissions
  • Required to configure ADFS relying party trusts
  • Needed to create and manage claim rules
  • Access to modify group memberships for role synchronization

Network and Security Requirements

• Network connectivity between ADFS server and Axero platform
  • ADFS metadata must be accessible from Axero's network location
  • Firewall rules must allow HTTPS traffic between systems
  • DNS resolution must work properly for all endpoints
• Access to ADFS Management Console and Axero Control Panel
  • Administrative access to configure relying party trusts
  • Ability to manage certificates and claim rules
  • PowerShell access for advanced ADFS configuration

User Login Experience

• Web: Users are redirected to your organization's ADFS login page for authentication. Optionally, users can log in with Axero credentials if EnableAutoLoginViaSaml is set to false.
• Mobile App: Users are redirected to the organization's ADFS login page and authenticate via ADFS, following the same SSO process as the web platform.
• Session Expiration: Controlled by FormsAuthPersistentCookieTimeOutInMinutes (default: 43,200 minutes = 30 days). If MakePermanentCookieForThirdPartyLogin is false, users are logged out when the browser closes.

ADFS Configuration

1. Log in to your ADFS server and open Server Manager.
2. Launch AD FS Management.
3. Right-click Relying Party Trusts > Add Relying Party Trust...
4. Choose Claims aware and click Start.
5. Select Enter data about the relying party manually > Next.
6. Enter a Display Name for your Axero application (e.g., "Axero Intranet") > Next.
7. Select AD FS profile (or AD FS 2.0 profile if prompted) > Next.
8. Optional Token Encryption: If you want to encrypt SAML tokens, you can upload Axero's public certificate here. Contact Axero support to obtain the appropriate certificate for your instance. Skip this step if token encryption is not required.
9. Enable Support for the SAML 2.0 WebSSO protocol.
10. Set the SAML 2.0 SSO service URL to https://yourdomain/SAML/AssertionConsumerService.aspx (replace yourdomain with your actual Axero domain).
11. Set the Relying party trust identifier. Use your Axero intranet URL (e.g., https://yourdomain) or a URN format (e.g., urn:company:axero). Important: This identifier must match exactly what you configure in Axero.
12. Choose Permit all users to access this relying party or configure specific access rules as needed.
13. Complete the wizard and close.
14. In Relying Party Trusts, right-click your new trust > Edit Claim Issuance Policy.
15. Click Add Rule and select Transform an Incoming Claim:
    • Incoming claim type: Windows account name
    • Outgoing claim type: Name ID
    • Outgoing name ID format: Unspecified
    • Pass through all claim values: Selected
    This rule is required for SAML authentication to work properly.
16. Click Add Rule and select Send LDAP Attributes as Claims to map user attributes (see User Data Mapping section).
17. Optionally, add additional rules for group membership or custom claims (see Role Syncing section).
18. Right-click your trust > Properties > Encryption tab. If using token encryption, select the Axero certificate you uploaded earlier.
19. Go to the Endpoints tab and add a SAML Logout endpoint:
    • Endpoint type: SAML Logout
    • Binding: Redirect
    • URL: https://yourdomain/SAML/SLOService.aspx
20. Open PowerShell as Administrator and run: Set-ADFSRelyingPartyTrust -TargetName "YourTrustDisplayName" -SamlResponseSignature MessageAndAssertion
    Note: Replace "YourTrustDisplayName" with the exact display name you used when creating the trust (use quotes if the name contains spaces).
21. Restart the ADFS service: Restart-Service adfssrv
22. Verify ADFS metadata is accessible at https://your-adfs-server/FederationMetadata/2007-06/FederationMetadata.xml

Certificate Coordination

ADFS uses a token-signing certificate to digitally sign SAML responses. Axero must have the matching public certificate to verify these signatures. Additionally, if you choose to encrypt SAML tokens, Axero's public certificate must be uploaded to ADFS.

Required Steps

1. Obtain Axero's Public Key:
   • Contact Axero support to obtain Axero's public key
2. Upload Axero Public Key to ADFS:
   • In your Relying Party Trust > Properties > Encryption tab
   • Upload or import Axero's public key for token encryption
3. Export ADFS Token-Signing Certificate:
   • Open ADFS Management Console > Service > Certificates
   • Right-click Token-signing certificate > View Certificate
   • Go to Details tab > Copy to File...
   • Export as Base-64 encoded X.509 (.CER) format
   • Save the file with a descriptive name (e.g., "ADFS-TokenSigning.cer")
4. Upload ADFS Certificate to Axero:
   • Use the exported .cer file as the "Partner Identity Certificate" in Axero's SAML configuration
   • The certificate must match exactly between both systems
5. Coordinate Axero Private Key:
   • Contact Axero support to coordinate the private key and password upload

Axero Configuration

1. Log in to your Axero site as an administrator.
2. Go to Control Panel > System > Single Sign On.
3. Select SAML from the dropdown and click Save.
4. Enter the following values (obtained from your ADFS metadata at https://your-adfs-server/FederationMetadata/2007-06/FederationMetadata.xml):
   • Partner Identity Provider URL: The EntityID value from the ADFS metadata (typically looks like https://your-adfs-server/adfs/services/trust)
   • Single Sign On Service URL: The SingleSignOnService Location URL from ADFS metadata (typically https://your-adfs-server/adfs/ls/)
   • Relying Party Trust Identifier: Must match exactly what you configured in ADFS (your Axero URL or URN)
   • Single Logout Service URL: The SingleLogoutService Location URL from ADFS metadata (typically https://your-adfs-server/adfs/ls/)
   • Partner Identity Certificate (CER): Upload the token-signing certificate exported from ADFS
5. Click Update to save the configuration.
6. Go to Control Panel > System > Advanced System Utilities and click Restart Site to apply the changes.
7. Test the SSO configuration by logging out and attempting to log back in.

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 Active Directory
   • Ensure the test user has all required attributes populated (givenName, sn, mail, etc.)
   • Verify the test user is enabled and can authenticate to ADFS
   • Try logging into Axero using SSO with this test account
2. Verify the login flow:
   • Navigate to your Axero site
   • You should be redirected to ADFS for authentication
   • After successful ADFS login, you should be redirected back to Axero
   • Check that user data is properly mapped and displayed in Axero
   • Verify that the user account was created automatically (if SAMLAutoUserCreation is enabled)
3. Test logout functionality:
   • Log out from Axero
   • Verify you are properly logged out of both Axero and ADFS
   • Ensure you cannot access protected Axero pages without re-authentication
4. Test attribute mapping:
   • Check that user profile information from Active Directory appears correctly in Axero
   • Verify first name, last name, email, and other mapped attributes are populated
   • Test with users who have different attribute combinations

Common Testing Issues

• Redirect loops: Check that callback URLs match exactly between ADFS and Axero. Verify the Relying Party Trust identifier is identical in both systems.
• Certificate errors: Ensure the token-signing certificate file is valid, properly uploaded to Axero, and matches the certificate currently used by ADFS.
• User not created: Verify that SAMLAutoUserCreation is enabled in System Properties, or pre-provision the user in Axero with a username that exactly matches the Active Directory username.
• Time synchronization errors: Ensure both ADFS and Axero servers have synchronized clocks (within 5 minutes). SAML assertions are time-sensitive.
• Claim rule issues: Verify that the required Name ID claim rule is configured in ADFS and that additional attribute claim rules are properly set up.

Advanced Testing

• Test with multiple browsers: Verify SSO works consistently across different browsers (Chrome, Firefox, Edge, Safari).
• Test role synchronization: If you've configured group-based role mapping, test with users who belong to different Active Directory groups.
• Test error scenarios: Try logging in with a disabled Active Directory account to ensure proper error handling.
• Performance testing: Monitor authentication response times during testing to identify potential performance issues.

User Management

• Automatic User Creation: When a user logs in to Axero for the first time via ADFS SSO, their account is created automatically if it does not already exist (if SAMLAutoUserCreation is enabled).
• Pre-provisioning Users: You can add users to Axero before SSO login by:
  • Bulk importing users (ensure usernames match Active Directory usernames exactly).
  • Manually creating users in Control Panel > People > Manage People.
  • Using the Axero REST API to import users programmatically.
• Username Matching: The Axero username must match the Active Directory username exactly (case-sensitive) for SSO to work correctly. This is typically the sAMAccountName attribute in Active Directory.
• Administrator Accounts: Existing administrator accounts will continue to work with SSO if their usernames match Active Directory usernames. You may need to verify and adjust permissions after enabling SSO.
• User Data Sync: User profile data is updated from Active Directory each time the user logs in via SSO (if SAMLAutoUserUpdate is enabled).

User Data Mapping

To import user profile data from ADFS to Axero, map LDAP 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 SAML claim type that ADFS will send (configured in your ADFS claim rules).

Common mappings between ADFS LDAP attributes and Axero fields:

Role Syncing

To sync user roles from Active Directory groups to Axero roles via ADFS:

1. In ADFS Management, go to your Relying Party Trust > Edit Claim Issuance Policy.
2. Click Add Rule and select Send Group Membership as a Claim.
3. Configure the rule:
   • User's group: Select the Active Directory group you want to map
   • Outgoing claim type: Select Role or create a custom claim type
   • Outgoing claim value: Enter the role name as it should appear in Axero
4. Repeat for additional groups/roles as needed.
5. Alternatively, use Send Claims Using a Custom Rule for more complex role mapping scenarios.

Advanced Options

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

• EnableAutoLoginViaSaml: When set to true (default), users are automatically redirected to ADFS for authentication. Set to false to display a login page where users can choose between Axero credentials and SSO login.
• SAMLAutoUserCreation: When set to true (default), new user accounts are automatically created in Axero when someone logs in via ADFS for the first time. Set to false to require manual user provisioning.
• SAMLUserEmailMatch: When set to true, enforces that the email address from ADFS must match an existing user's email in Axero for SSO login to succeed. Useful for additional security validation.
• SAMLAutoUserUpdate: When set to true (default), user profile information is automatically updated from ADFS claims each time the user logs in via SSO.
• FormsAuthPersistentCookieTimeOutInMinutes: Controls how long users stay logged in (default: 43,200 minutes = 30 days).
• MakePermanentCookieForThirdPartyLogin: When set to false, users are logged out when they close their browser, regardless of the timeout setting above.

Troubleshooting

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

Authentication Issues

Certificate and Security Issues

User Data and Attribute Mapping Issues

User Provisioning and Access Issues

Infrastructure and Connectivity Issues

Best Practices

Security Best Practices

• Always use HTTPS: Ensure all Axero and ADFS 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 claim rules for user attributes that are actually needed in Axero. Avoid sending sensitive or unnecessary personal information through SAML assertions.
• Regular access reviews: Periodically audit user access in both Active Directory and Axero. Remove or disable accounts for users who no longer require access. Remember that disabling a user in AD 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 ADFS Event 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:
  • ADFS relying party trust configuration
  • Claim rule mappings and 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 your ADFS server to maintain accurate time synchronization. SAML assertions are time-sensitive and will fail with significant clock drift (typically more than 5 minutes). For cloud-hosted Axero instances, time synchronization is managed automatically.
• Certificate lifecycle management: Monitor SSL certificate expiration dates and plan renewals well in advance. When rotating certificates in ADFS, immediately update the corresponding certificate in Axero and restart the site.
• Plan for user lifecycle management: Establish processes for:
  • Onboarding new users and configuring appropriate claims
  • 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 ADFS 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 redundancy for critical ADFS components if your organization requires high uptime for authentication services.
• Regular health checks: Implement monitoring to detect ADFS service failures, certificate issues, or network connectivity problems 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.
• 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 Axero and ADFS Event Logs (Applications and Services Logs > AD FS > Admin)
• Browser and operating system information for affected users

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