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 SSO for your organization using ADFS as the identity provider.

Using a different identity provider? See Single Sign-On (SSO) for the other setup guides.

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: On ADFS 2.0 the same settings exist, but the wizard screens are named and ordered differently
• 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 sign 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. Sign 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 Send LDAP Attributes as Claims:
    • Attribute store: Active Directory
    • LDAP Attribute: SAM-Account-Name
    • Outgoing Claim Type: Name ID
    This rule is required for SAML authentication to work properly. Axero builds the account name from the value in this claim, so SAM-Account-Name gives you an Axero account name that matches the Active Directory logon name exactly.
    Other ways to fill Name ID, and what each one produces:

    • User-Principal-Name in the same rule sends jsmith@company.com. Axero keeps the part before the "@" sign, so the account name is still jsmith. Use this if your Active Directory logon names are not unique across domains.
    • Windows account name, sent with a Transform an Incoming Claim rule, arrives in the form DOMAIN\jsmith. Axero stores that whole string, domain prefix included, as the account name. Older Axero setups were configured this way, so an existing site may already have account names in that form.

    Choose one and stay with it. Switching later changes the account names Axero builds, and people who already have accounts will not match the new ones.
16. Add the profile attributes you want to bring across, such as first name, last name, and email. Put them in the rule you just created, or add a second Send LDAP Attributes as Claims rule for them. See the User Data Mapping section for the attributes and claim types to use.
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
    Note: Axero signs the logout request it sends to this endpoint, using the service certificate covered in Certificate Coordination. Adding the endpoint here is only half the job; single logout will not work until that certificate is in place.
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. Confirm the trust is signing with SHA-256, which Axero requires for all SAML transactions. In AD FS Management, right-click your trust > Properties > Advanced tab, and set Secure hash algorithm to SHA-256.
    Note: AD FS sets SHA-256 by default, so this step usually confirms the setting rather than changing it. A trust carried forward from an older AD FS version can still be on SHA-1, which Axero will reject.
22. Restart the ADFS service: Restart-Service adfssrv
23. Verify ADFS metadata is accessible at https://your-adfs-server/FederationMetadata/2007-06/FederationMetadata.xml

Certificate Coordination

An ADFS integration involves two certificates, and only the first is always required. That one is the ADFS token-signing certificate, which ADFS uses to sign the SAML responses it sends; Axero needs its public half, uploaded as the Partner Identity Certificate, to verify those signatures. The second is Axero's own service certificate, which Axero uses to sign the messages it sends back to ADFS. Whether you need that one depends on the two features described below.

The service certificate covers two features: single logout, and token encryption. You get neither automatically. Single logout works only once the logout endpoint and URL are set up on both sides, and token encryption stays off unless you turn it on. If you are using neither, skip the service certificate and set up sign-in without it. Where single logout is in use, Axero signs the logout request it sends and the service certificate holds the key it signs with, so single logout does not work without it. Sign-in keeps working either way, which is why a missing service certificate usually shows up later as a logout problem rather than a setup failure. None of this is specific to ADFS. Axero signs logout requests the same way for every SAML identity provider, so an Okta or PingFederate integration that uses single logout needs the service certificate just as much.

Required Steps

Steps 3 and 4 apply to every ADFS integration. Steps 1, 2, and 5 apply only if you are using single logout or token encryption; skip them if you are using neither.

1. Obtain Axero's Public Key (single logout or token encryption only):
   • Contact Axero support to obtain Axero's public key
2. Upload Axero Public Key to ADFS (single logout or token encryption only):
   • For single logout, add it on the Signature tab of your Relying Party Trust. ADFS uses it to check the signature on the logout requests Axero sends, and rejects those requests when it is missing.
   • For token encryption, add it on the Encryption tab instead. That is the tab ADFS uses to encrypt the tokens it sends to Axero.
   • If you are using both features, add it in both places.
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's Service Certificate (single logout or token encryption only):
   • Contact Axero support to coordinate the service certificate and its password.
   • This certificate must be a .pfx file. The Partner Identity Certificate above accepts .cer, .cert or .pfx, but the service certificate upload accepts .pfx only, because it carries the private key Axero signs with.
   • The .pfx has its own password, and Axero stores the file and the password separately. Record both. Replacing the file later means updating the password too, even when the password has not changed.

Axero Configuration

1. Sign 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. Test the SSO configuration by signing out and signing 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 signing in to 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 signing 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 (give each person the account name that ADFS will send, as described under Username Matching below).
  • Manually creating users in Control Panel > People > Manage People.
  • Using the Axero REST API to import users programmatically.
• Username Matching: Axero does not read a name out of Active Directory. It takes the value ADFS sends in the Name ID claim and keeps everything before the "@" sign, so a Name ID of jsmith@company.com produces the account name jsmith. Match on that value when you pre-provision people. Capitalization does not matter, because Axero compares account names without regard to case. If no account name matches, Axero looks for an existing person with the same email address before it decides to create a new account.
• 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 can be either the full claim type that ADFS sends (for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname) or just the short attribute name (givenname). Axero checks the short name against the same claim type namespace, so both forms find the value.

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.
6. In Axero, go to Control Panel > System > System Properties, set SCIMSyncRoles to true. The change takes effect on the next sign-in and does not need a site restart. Axero ignores the role claims until this is on, so the rest of this section has no effect without it. The property name mentions SCIM, but the same setting controls role syncing for ADFS logins.

Advanced Options

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

• EnableAutoLoginViaSaml: Default is false, which shows the Axero login page with both options, so people can sign in with ADFS or with Axero credentials. Set it to true to send everyone straight to ADFS. You can set the same thing on the Single Sign On page with the SSO Login Only option, which is easier to find than the property. Turn it on only after you have confirmed SSO works, because it removes the credential login for everyone, administrators included.
• 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: Default is false. It decides what Axero does when someone signs in with an account name that matches an existing person, but an email address that does not. Left at false, Axero treats them as the same person and updates the email on the existing account. Set to true, Axero treats them as two different people and creates a second account with a new account name. It does not block the login. Use it only where account names get reused between people, and be aware it can produce duplicate accounts after somebody's email address changes in Active Directory.
• SAMLAutoUserUpdate: When set to true (default), user profile information is automatically updated from ADFS claims each time the user logs in via SSO.
• SCIMSyncRoles: Default is false. Set it to true to apply the role claims ADFS sends. See Role Syncing for what changes once it is on.
• FormsAuthPersistentCookieTimeOutInMinutes: Controls how long people stay signed 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.

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 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.
• Tell people what to expect: Explain the new sign-in path before you switch it on, and tell people who to contact when ADFS turns them away. The Axero site cannot resolve an ADFS 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 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.