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, seamless 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 - Main application configuration file
  • WindowsADSettings.config - AD-specific 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 experience seamless automatic login when properly 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 must manually enter their AD credentials. Automatic login is not supported on macOS.
• Mobile App: Users log 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, users are logged out when the browser closes.

Active Directory & 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, ensure:

      <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. Remove or comment out any line containing:

      <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 contains AD-specific settings for advanced features like PDF export and group synchronization.
   • Configure service account credentials for system operations:

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

   • For AD group synchronization, configure the RoleGroupsContainer key with pipe-separated Distinguished Names of AD groups to import as Axero roles:

     <add key="RoleGroupsContainer" value="CN=AxeroUsers,OU=Security Groups,DC=company,DC=com|CN=AxeroAdmins,OU=Security Groups,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.
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 AuthServerWhitelist policy to include your Axero domain (e.g., *.company.com)
     • Registry: Add your domain to HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\AuthServerWhitelist or HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Edge\AuthServerWhitelist
   • Firefox: In about:config, add your Axero domain to network.automatic-ntlm-auth.trusted-uris (e.g., https://axero.company.com).

Axero Configuration

1. Log into 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 sync frequency in minutes (recommended range: 120–1380 minutes)
   • 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 logging into 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 experience seamless automatic login 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 automatically creates user accounts the first time someone successfully authenticates via Active Directory.
• Pre-Provisioning Users: You can create user accounts in advance using:
  • Bulk Import: Upload a CSV file with user information (usernames must exactly match AD usernames)
  • 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, ensure their usernames exactly match their AD usernames
  • 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.

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 Distinguished Names for AD groups that should be imported as Axero roles
  • Example: CN=AxeroUsers,OU=Security Groups,DC=company,DC=com|CN=AxeroAdmins,OU=Security Groups,DC=company,DC=com
• 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 (specified in minutes)
  • Recommended range: 120-1380 minutes (2-23 hours) depending on your organization's needs
  • 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 appropriate sync intervals: Balance between data freshness and system performance (recommended: 2-23 hours).
• Create emergency access procedures: Maintain at least one local administrator account that doesn't depend on AD 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 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.
• Capacity planning: Monitor resource usage during peak authentication times and sync operations.

User Experience

• Provide user training: Educate users about the SSO experience, especially for Mac users who need to enter credentials manually.
• Clear error messaging: Ensure users understand what to do when authentication fails.
• Browser compatibility guidance: Provide instructions for configuring different browsers for optimal SSO experience.
• Support multiple platforms: Document the different authentication experiences across Windows, Mac, and mobile platforms.

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.