Active Directory SSO | Axero Documentation

This guide provides step-by-step instructions for integrating Microsoft Active Directory (AD) Single Sign-On (SSO) with your self-hosted Axero platform. By following this guide, you will enable secure SSO for your organization using Windows Authentication and AD.

Prerequisites

Before implementing Active Directory SSO with your Axero platform, ensure you have the following requirements in place:

System Requirements

• Self-hosted Axero intranet site with administrator access
  • This configuration is not available for cloud-hosted sites
  • Cloud customers should contact Axero support for SSO assistance
• Windows Server with IIS (Internet Information Services) where Axero is hosted
  • IIS must have the Windows Authentication module installed and available
  • Server should be domain-joined for optimal performance
• SSL certificate for your Axero site
  • HTTPS is required for secure authentication
  • Certificate must be valid and trusted by client browsers

Active Directory Environment

• Microsoft Active Directory environment with domain controller access
  • Active Directory Domain Services (AD DS) must be properly configured
  • Domain controllers should be accessible from the Axero server
  • Time synchronization between all servers is critical for Kerberos authentication
• Domain administrator privileges or equivalent permissions
  • Required to configure authentication settings
  • Needed to create service accounts if necessary
  • Access to modify group memberships for role synchronization
  • Permissions to register Service Principal Names (SPNs) if using Kerberos

File System Access

• Configuration file access to Axero's core files
  • web.config: the main application configuration file
  • WindowsADSettings.config: the Active Directory settings file
  • Backup copies of original files before making changes
• Directory permissions for application functionality
  • Write access to Assets folder for file uploads
  • Appropriate NTFS permissions for the IIS application pool identity

User Login Experience

• Windows (Domain-joined computers): Users are signed in automatically once everything below is configured. No username/password prompt appears for domain users on domain-joined machines with properly configured browsers.
• Windows (Non-domain computers): Users are prompted to enter their AD credentials in the format DOMAIN\username.
• Mac: Users enter their AD credentials manually. Macs are usually not joined to the domain, so the browser has no Windows credentials to pass through and automatic sign-in does not happen.
• Mobile App: Users sign in with their AD credentials using the format DOMAIN\username.
• Session Management: Session duration is controlled by FormsAuthPersistentCookieTimeOutInMinutes (default: 30 days). When MakePermanentCookieForThirdPartyLogin is set to false, people are signed out when the browser closes.

Active Directory and IIS Configuration

1. Configure Windows Authentication in IIS
   1. Open IIS Manager on your Windows Server.
   2. Navigate to Application Pools, select your Axero application pool, and set the Identity to NetworkService or a specific domain service account.
   3. Select your Axero website or virtual directory in the left panel.
   4. Double-click Authentication in the main panel.
   5. Configure authentication methods:
      • Enable: Windows Authentication only
      • Disable: Anonymous Authentication, Basic Authentication, and all other methods
      Note: Basic Authentication is not recommended for AD SSO as it transmits credentials in base64 encoding without encryption. Windows Authentication provides proper SSO functionality with secure credential handling.
   6. Right-click Windows Authentication and select Advanced Settings:
      • Ensure NTLM is listed as the first (top) provider
      • Set Extended Protection to Accept (recommended) or Off only if you experience compatibility issues with older clients
   7. Configure folder permissions for file operations:
      • Navigate to your Axero installation's Assets folder and any upload directories
      • Remove Full Control permissions for security
      • Grant the following permissions to the IIS application pool identity and relevant user groups: Modify, List Folder Contents, Read, and Write
2. Configure web.config for Windows Authentication
   1. Locate and open the web.config file in your Axero installation directory.
   2. In the <system.webServer> section, confirm this line is present. Axero ships with it already set, so this is normally a check rather than an edit:

      <modules runAllManagedModulesForAllRequests="true">

      Note: For static content directories (like Assets), you may need to set this to "false" in separate web.config files within those directories to improve performance.
   3. Search the file for the following line and remove it or comment it out if it is there. A standard Axero installation does not include it, so on most sites there is nothing to change here:

      <remove name="WindowsAuthentication" />

   4. In the <system.web> section, add or modify:

      <authentication mode="Windows" />
      <authorization>
        <deny users="?" />
      </authorization>

   5. Important for Cloud Customers: If you have a cloud-hosted Axero site, do not modify these files directly. Contact Axero support for assistance with SSO configuration.
3. Configure Service Principal Names (SPNs) for Kerberos (Optional but Recommended)
   
   
   What are SPNs? Service Principal Names are unique identifiers for services running on servers. They're required for Kerberos authentication to work properly and provide better security than NTLM.
   1. Open Command Prompt as Administrator on a domain controller or computer with AD management tools
   2. Register SPNs for your Axero site using the setspn command:

      setspn -A HTTP/your-axero-site.company.com DOMAIN\ServiceAccount
      setspn -A HTTP/your-axero-site DOMAIN\ServiceAccount

      Replace your-axero-site.company.com with your actual Axero URL and DOMAIN\ServiceAccount with your application pool identity account.
   3. Verify SPNs are registered correctly:

      setspn -L DOMAIN\ServiceAccount

4. Configure WindowsADSettings.config
   • This file holds the Active Directory settings. Start with DomainName, because Axero reads nothing from Active Directory until it is set, which leaves accounts without profile data and stops role syncing.
   • Set your domain name. This key ships empty, and while it is empty Axero stops before it reads anything from Active Directory and writes "DomainName is empty in WindowsADSettings.config" to the error log:

     <add key="DomainName" value="company.com"/>

   • Configure service account credentials for system operations:

     <add key="HttpAuthenticationUsername" value="DOMAIN\ServiceAccount"/>
     <add key="HttpAuthenticationPassword" value="SecurePassword"/>

   • For AD group synchronization, point the RoleGroupsContainer key at the part of the directory that holds the groups you want to bring in. Give the organizational units that contain the groups, not the groups themselves, and separate multiple entries with the pipe character:

     <add key="RoleGroupsContainer" value="OU=Security Groups,DC=company,DC=com|OU=Instructors,OU=Sales,DC=company,DC=com"/>

     What are Distinguished Names? Distinguished Names (DNs) are the full path to an object in Active Directory, similar to a file path. They uniquely identify groups, users, or organizational units in your AD structure. An organizational unit starts with OU=, and a group starts with CN=. This setting takes the OU= form.
     Note: Leaving this key empty is also valid. Axero then brings in every group the person belongs to, anywhere in the domain. Use the key when you want to limit role syncing to groups in specific organizational units.
   • Check the remaining keys in the file before you finish. These ship with working defaults, but each one changes what this page describes:

     Key	Ships as	What it does
     DomainName	empty	Required. Your Active Directory domain. Nothing reads from Active Directory until this is set.
     AllowAutoRegistration	true	Creates an Axero account the first time somebody signs in. Set it to false to require accounts to exist beforehand.
     CopyRolesFromAD	true	Brings Active Directory group memberships in as Axero roles. Role syncing does nothing when this is false, whatever else you configure.
     StripDomainName	true	Removes the domain prefix when an account is created, so DOMAIN\jsmith becomes jsmith. Set it to false where you have more than one domain, and accounts are created as DOMAIN_jsmith instead.
     DomainUsernameConnectorSymbol	_	The character that joins domain and name when StripDomainName is false.
     RequiredADGroupForMembership	empty	Restricts access to members of one named group. Leave it empty to allow everyone in the domain.
     TextToStripFromGroups	a single space	Text removed from each group name before it becomes a role name, for cases where group names carry a prefix such as "IT - ".

5. Configure Client Browsers for Automatic Login
   • Internet Explorer/Edge Legacy: Go to Internet Options > Security > Local Intranet > Sites, and add your Axero site URL. Then go to Custom Level and set User Authentication > Logon to Automatic logon with current user name and password.
   • Chrome/Edge Chromium: Configure via Group Policy or registry:
     • Group Policy: Set AuthServerAllowlist policy to include your Axero domain (e.g., *.company.com)
     • Registry: Add your domain to HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\AuthServerAllowlist or HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\AuthServerAllowlist
   • Firefox: In about:config, add your Axero domain to network.automatic-ntlm-auth.trusted-uris (e.g., https://axero.company.com).

Axero Configuration

1. Sign in to your Axero site as an administrator.
2. Navigate to Control Panel > System > System Properties.
3. Configure the following settings:
   • Set ActiveDirectoryAuthEnabled to true to enable AD authentication
   • Set ActiveDirectorySyncManagerInterval to control how often the sync runs. The value is in minutes, but Axero rounds it down to whole hours, so use a multiple of 60. Anything under 60 minutes, or 1440 minutes (24 hours) and above, is ignored: the sync falls back to every 120 minutes and a warning is written to the error log.
   • Set ADSyncEnabled to true to enable automatic user data synchronization
   • Set ADSyncProfilePicture to true to sync profile pictures from AD, or false to allow users to manage their own profile pictures
4. Save the configuration and restart the application pool in IIS to apply changes.

Testing Your Configuration

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

Initial Testing Steps

1. Test with a single domain user account:
   • Use an existing test user account in Active Directory
   • Ensure the test user has all required attributes populated (name, email, department, etc.)
   • Verify the user is a member of any AD groups configured for role synchronization
   • Try signing in to Axero from a domain-joined computer
2. Verify the authentication flow:
   • Navigate to your Axero site from a domain-joined computer
   • For domain users on domain computers: Login should be automatic with no prompts
   • For non-domain computers: Users should be prompted for credentials in DOMAIN\username format
   • Check that user data is properly synchronized and displayed in Axero
   • Verify that AD group memberships are reflected as Axero roles (if configured)
3. Test different browser configurations:
   • Test with Internet Explorer/Edge (should work automatically if in Local Intranet zone)
   • Test with Chrome/Firefox (may require browser configuration for automatic login)
   • Verify that browsers prompt for credentials when automatic login is not configured
4. Test user data synchronization:
   • Navigate to Control Panel > System > Sync Active Directory Data > Sync Now
   • Manually trigger a sync and verify user information updates correctly
   • Check that profile pictures sync if ADSyncProfilePicture is enabled
   • Verify that department changes in AD are reflected in Axero after sync

Platform-Specific Testing

• Windows Domain-Joined Computers: Should log in automatically without any credential prompts
• Windows Non-Domain Computers: Should prompt for DOMAIN\username and password
• Mac Computers: Will always prompt for DOMAIN\username and password (automatic login not supported)
• Mobile Devices: Should prompt for domain credentials in the mobile app

Common Testing Issues

• Authentication prompts on domain computers: Check browser security zone configuration and ensure Axero site is in Local Intranet zone
• User account not created: Verify that the user exists in AD and that automatic user creation is working properly
• Profile data not syncing: Check attribute mappings and ensure LDAP attributes are populated in Active Directory
• Kerberos/NTLM failures: Verify SPNs are registered correctly and check Windows Event Logs for authentication errors
• Time synchronization errors: Ensure all servers have synchronized clocks (critical for Kerberos)

User Management

• Automatic User Creation: When AD SSO is enabled, Axero creates an account the first time someone signs in successfully through Active Directory. This is controlled by the AllowAutoRegistration key in WindowsADSettings.config, which ships set to true. Set it to false if you want accounts to exist in Axero before anyone can sign in.
• Pre-Provisioning Users: You can create user accounts in advance using:
  • Bulk Import: Upload a CSV file with user information. Give each person the account name Axero will build for them: the Active Directory name on its own when StripDomainName is true, or DOMAIN_name when it is false. Capitalization does not matter
  • Manual Creation: Use Control Panel > People > Manage People > Add User
  • REST API: Programmatically create users for automated provisioning workflows
• Administrator Account Management:
  • If administrator accounts exist before enabling AD SSO, make sure each account name matches the name Active Directory will send for that person
  • If usernames don't match, you'll need to update user permissions after SSO is enabled
  • Consider creating a local emergency administrator account that doesn't rely on AD authentication
• User Deactivation:
  Important: Disabling or deleting a user in Active Directory does not automatically disable their Axero account. You must manually ban or delete users in Axero when they leave the organization to prevent unauthorized access.
  
  Manual removal is not the only option. If you want departures handled automatically, that is what SCIM provisioning does, and it is available through Entra ID, Okta and OneLogin rather than through Active Directory SSO on its own. See those setup guides if automatic deactivation matters to you.
  What Active Directory SSO does and does not cover. It signs people in with their directory credentials, creates an Axero account on first sign-in, and keeps mapped profile fields in step at each sign-in. It does not create accounts ahead of first sign-in, and it does not deactivate anyone when they are disabled or removed in the directory; those are the two things adding SCIM provisioning changes. Group and role membership arrive through claims either way.

User Data Mapping

Configure automatic synchronization of user profile information from Active Directory to Axero by mapping LDAP attributes to Axero user fields:

1. In Axero, navigate to Control Panel > System > Sync Active Directory Data > Mapping.
2. Create attribute mappings where the LDAP Attribute corresponds to the AD field and the Axero Field corresponds to the user profile field in Axero.

Common mappings between Active Directory LDAP attributes and Axero fields:

Role Syncing

Automatically synchronize Active Directory group memberships with Axero user roles:

• Configure AD Group Import:
  • In the WindowsADSettings.config file, configure the RoleGroupsContainer setting
  • Provide a pipe-separated list of the organizational units that hold those groups. Give the containers, not the groups themselves
  • Example: OU=Security Groups,DC=company,DC=com|OU=Instructors,OU=Sales,DC=company,DC=com
  • Leave the setting empty to bring in every group the person belongs to
  • Confirm CopyRolesFromAD is set to true in the same file. Role syncing does nothing while it is false
• Automatic Role Updates: When users are added to or removed from specified AD groups, their corresponding Axero roles are automatically updated during the next synchronization cycle.
• Group Naming: AD group names become Axero role names. Ensure your AD group names are appropriate for display in Axero.

Advanced Options

• Synchronization Frequency:
  • Adjust ActiveDirectorySyncManagerInterval to control how often user data synchronizes. The value is in minutes and is rounded down to whole hours, so 90 minutes runs hourly. Use a multiple of 60.
  • Valid range: 1 to 23 hours. Give it in minutes as a multiple of 60, so 60 through 1380. A value under 60 minutes, or 1440 minutes and above, is ignored and the sync runs every 120 minutes.
  • The schedule is read when the site starts, so restart the application pool after changing it.
  • More frequent syncing provides faster updates but increases server load
• Manual Synchronization:
  • Navigate to Control Panel > System > Sync Active Directory Data > Sync Now
  • Use this to immediately synchronize user data without waiting for the scheduled interval
  • Useful for testing configuration changes or onboarding new users quickly
• Profile Picture Management:
  • Set ADSyncProfilePicture to true to automatically sync profile pictures from AD
  • Set to false to allow users to upload and manage their own profile pictures in Axero
  • When enabled, user-uploaded pictures are overwritten during sync

Troubleshooting

Common issues and their solutions when implementing Active Directory SSO with Axero:

Authentication Issues

Synchronization Issues

System and Performance Issues

Platform-Specific Issues

Best Practices

Security Best Practices

• Always use HTTPS: Secure all Axero endpoints with valid SSL certificates. HTTP is not secure for authentication.
• Implement least privilege access: Only grant necessary permissions to service accounts and user groups.
• Limit attribute exposure: Only map and synchronize user attributes that are necessary for your intranet's operation.
• Regular access reviews: Periodically audit user access in both Active Directory and Axero to ensure appropriate permissions.
• Secure service accounts: Use strong passwords for service accounts and consider using Managed Service Accounts where possible.
• Monitor authentication logs: Regularly review Windows Event Logs and Axero logs for failed authentication attempts or suspicious activity.
• Use Kerberos when possible: Configure SPNs properly to enable Kerberos authentication, which provides better security features than NTLM.

Configuration Management

• Document your configuration: Maintain detailed, secure documentation of all SSO-related settings, including:
  • IIS authentication settings
  • Web.config modifications
  • WindowsADSettings.config parameters
  • Attribute mappings
  • Group synchronization settings
  • SPN registrations
• Version control configuration files: Keep backups of working configurations before making changes.
• Test in staging environment: Always validate configuration changes with test users in a non-production environment first.
• Plan rollback procedures: Have a documented process to quickly revert changes if issues arise.

Operational Best Practices

• Maintain time synchronization: Use NTP or Windows Time Service to keep all servers (AD controllers, Axero server) synchronized to avoid Kerberos authentication issues.
• Plan for user lifecycle management: Establish processes for:
  • Onboarding new users
  • Updating user information when roles change
  • Deactivating users when they leave the organization
• Set a sync interval you can live with: ActiveDirectorySyncManagerInterval accepts 1 to 23 hours, given in minutes as a multiple of 60. Shorter intervals mean fresher data and more load on the domain controller.
• Create emergency access procedures: Maintain at least one local administrator account that doesn't depend on AD authentication.

Performance and User Experience

• Monitor system performance: Track authentication response times and sync operation duration.
• Plan for high availability: Consider redundancy for critical components if your organization requires high uptime.
• Regular health checks: Implement monitoring to detect authentication or synchronization failures quickly.
• Tell people what to expect: The sign-in experience is not the same on every device. A domain-joined Windows machine signs people in without a prompt, while Mac users are asked for their credentials. Say so before you switch it on, and tell people who to contact when the prompt rejects them.

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 and logs from multiple sources:
  • Windows Event Logs: Review the following Windows Event Log categories:
    • Security Log: Authentication success/failure events (Event IDs 4624, 4625, 4648)
    • System Log: Service and system-level errors related to authentication
    • Application Log: IIS and .NET application errors
  • IIS Logs: HTTP request logs showing authentication attempts and response codes
  • Active Directory logs: Domain controller logs showing authentication requests and LDAP queries
• Browser and operating system information for affected users

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