Setup Guide: Entra ID SAML SSO | Axero Documentation

This guide explains how to configure Microsoft Entra ID (formerly Azure Active Directory) for Single Sign-On (SSO) without automatic user provisioning. Users will log in with their Entra ID credentials, but their accounts will be managed in Axero.

To enable automatic user provisioning, see the Setup Guide for SCIM Provisioning.

Overview

• Preparation
• Step 1: Configure Entra ID
• Step 2: Configure Axero
• Step 3: Test SSO Integration
• Optional: Add Custom Attributes
• Optional: Configure User Syncing
• Optional: Configure Roles Import
• Additional Considerations

Preparation

Before you start, ensure you have:

• Global Administrator or Application Administrator role in your Microsoft Entra ID tenant
• Site Administrator access to your Axero site
• Confirmed the following Axero System Properties are configured:
  • Navigate to Control Panel > System > System Properties
  • EnableAutoLoginViaSaml = False
  • SAMLAutoUserCreation = True
  • SAMLAutoUserUpdate = True
  • SAMLUserEmailMatch = False
• Adjusted the following settings for your planned usernames:
  • Navigate to Control Panel > System > General Settings > Advanced Settings
  • Update Minimum length for username and Maximum length for username as needed to accommodate your planned username format

Important: Adjusting these settings will help prevent potential errors during user creation and login. Ensure your site URL is finalized before proceeding, as changing it later requires Enhanced Support assistance and reconfiguration of SSO integrations.

Step 1: Configure Entra ID

1.1 Create a New Enterprise Application

1. Sign in to the Microsoft Entra admin center with an account that has at least Application Administrator or Global Administrator role.
2. Browse to Entra ID > Enterprise apps.
3. Select New application.
   
4. Select Create your own application.
   
5. Enter a name for your application (for example, "Axero SSO"). Ensure "Integrate any other application you don't find in the gallery (Non-gallery)" is selected.
   
6. Select Create. You'll be taken to the application overview page.
   

1.2 Configure SAML Single Sign-On

1. Select Single sign-on from the navigation menu, then select SAML.
   
2. In the Basic SAML Configuration section, select Edit and configure the following:
   • Identifier (Entity ID): Select Add identifier and enter your Axero site URL without a trailing slash (for example, https://your-axero-site.com)
   • Reply URL (Assertion Consumer Service URL): Select Add reply URL and enter your Axero site URL followed by /SAML/AssertionConsumerService.aspx (for example, https://your-axero-site.com/SAML/AssertionConsumerService.aspx)
   • Sign on URL: Enter your Axero site URL followed by /login (for example, https://your-axero-site.com/login)
     
   • Relay State: Leave this field blank
   • Logout URL: Leave this field blank
3. Select Save to apply the configuration.

1.3 Configure User Assignment

1. Select Properties from the left navigation menu.
   
2. For open access: Set Assignment required? to No to allow all Entra ID users to access the application without explicit assignment. Select Save.
   
3. For controlled access (Recommended): Set Assignment required? to Yes to require explicit user or group assignment. Select Save.
   
   To assign users or groups:
   1. Select Users and groups from the left navigation menu
   2. Select Add user/group
   3. Under Users, select None Selected
   4. Search for and select the desired users or groups
   5. Select Select
   6. Select Assign

1.4 Configure SAML Signing and Download Metadata

1. Select Single sign-on from the navigation menu.
2. In the SAML Certificates section, select Edit.
   
3. Configure the signing settings:
   • Signing Option: Select Sign SAML response and assertion (Required)
   • Signing Algorithm: Select SHA-256
   
4. Select Save to apply the certificate settings and close the pane.

5. Select Download next to Federation Metadata XML. Save this file as you'll need it to configure Axero in the next step.
   

Step 2: Configure Axero

2.1 Access Axero SSO Settings

1. Sign in to your Axero site with a Site Administrator account.
2. Navigate to Control Panel > System > Single Sign-On.

2.2 Configure SSO Settings

1. On the Settings tab, select Azure Active Directory as your authentication method.
   
2. Select Save to apply the authentication method.
   
3. Select Choose File and upload the Federation Metadata XML file you downloaded in step 1.4.
   
4. Choose your login configuration:
   • SSO Login + Communifire Login (Recommended for initial setup): Allows users to log in with either Entra ID or Axero credentials. This provides a fallback option during testing. See the instructions for adding a "Login via SSO" button to your login page.
   • SSO Login Only: Forces all users to authenticate via Entra ID and redirects the login page to Entra ID. Warning: Only select this option after thoroughly testing SSO functionality to avoid locking out administrators.
     

Step 3: Test SSO Integration

1. Assign test user to the application (if Assignment required = Yes):
   • In the Microsoft Entra admin center, navigate to your Axero enterprise application
   • Select Users and groups from the left navigation
   • Select Add user/group
   • Under Users, select None Selected
   • Search for and select your user account, then select Select
   • Select Assign to complete the assignment
2. Configure SSO login button (if using "SSO Login + Communifire Login"):
   • Follow the instructions for adding a "Login via SSO" button to your login page
3. Test the SSO login flow:
   • Critical: Open a new incognito/private browser window to ensure a clean session
   • Navigate to your Axero site's login page
   • Select the Login via SSO button (or you'll be automatically redirected if using "SSO Login Only")
   • Verify redirection to the Microsoft Entra ID login page
   • Enter your Microsoft Entra ID credentials
   • Confirm successful authentication and redirection back to Axero
   • Verify you are logged into Axero with the correct user account
4. Verify user attribute mapping:
   • Once logged in, navigate to your user profile in Axero
   • Confirm that First name, Last name, and Email address are populated correctly from Entra ID
   • If attributes are missing or incorrect, review the attribute mapping configuration
5. Test logout functionality:
   • Select the logout option in Axero
   • Verify that you are successfully logged out of Axero
   • Note: Single logout from Entra ID is not automatically configured in this setup
6. Test automatic user provisioning:
   • Assign a different test user to the Axero application in Entra ID
   • Have the test user attempt SSO login to Axero
   • Verify that a new user account is automatically created in Axero
   • Confirm the new user's profile information is correctly populated

Optional: Add Custom Attributes

Microsoft Entra ID includes three default claims that Axero requires:

You can configure claims to map additional user profile information from Entra ID to Axero. These attributes will be updated each time a user logs in via SSO.

4.1 Configure Additional Claims in Entra ID

1. In the Microsoft Entra admin center, navigate to Entra ID > Enterprise apps and select your Axero SSO application.
2. Select Single sign-on from the left navigation menu.
3. In the Attributes & Claims section, select Edit.
   
4. Select Add new claim to create additional attribute mappings.
5. For each claim, enter the Name (exactly as shown in the table below) and select the corresponding Source attribute. Leave the Namespace field blank and select Save.
   

   Commonly used attributes:

   Claim Name	Source Attribute	Description
   companyName	user.companyname	Company/Organization name
   department	user.department	Department
   jobTitle	user.jobtitle	Job title
   employeeId	user.employeeid	Employee ID number
   employeeHireDate	user.employeehiredate	Employee hire date
   officeLocation	user.officelocation	Office location
   businessPhone	user.telephonenumber	Business phone number
   mobilePhone	user.mobilephone	Mobile phone number
   streetAddress	user.streetaddress	Street address
   city	user.city	City or locality
   state	user.state	State or region
   country	user.country	Country
   postalCode	user.postalcode	Postal code

   Note: To synchronize manager relationships and profile pictures, see Optional: Configure User Syncing.

4.2 Configure Attribute Mapping in Axero

1. In Axero, navigate to Control Panel > System > Single Sign-On.
2. Select the Data Mapping tab.
3. For Type, select Azure Active Directory.
   
4. Select Add to create a new attribute mapping.
   
5. Add a mapping for each desired attribute, ensuring the property names match exactly as configured in Entra ID. Select the corresponding Axero profile field from the dropdown.
   
6. Remove any unused or incorrect mappings by selecting the delete option.
7. Select Update to save all mapping configurations.
8. Test the attribute mappings by logging in via SSO. Ensure the test user is assigned to the application in Entra ID (see Step 1.3 Configure User Assignment).

Optional: Configure User Syncing

User syncing enables automatic updates of user profile information from Entra ID to Axero at scheduled intervals, without requiring users to log in. This feature is necessary for synchronizing manager relationships and profile pictures, and provides a more comprehensive alternative to login-only attribute updates.

5.1 Configure App Registration for Microsoft Graph API

1. In the Microsoft Entra admin center, navigate to Identity > Applications > App registrations.
2. Select All applications and open the application you created for SSO.
3. Copy the Application (client) ID from the overview page and save it for later use.
   
4. Select API permissions from the navigation menu.
   
5. Select Add a permission, then choose Microsoft Graph.
   
6. Add Application permissions (recommended for automated syncing):
   • Select Application permissions
   • Search for and select Directory.Read.All
   • Search for and select User.Read.All
   • Select Add permissions
   
   
7. Grant admin consent: Select Grant admin consent for [Your Organization] and confirm by selecting Yes.
   

5.2 Create Client Secret for Authentication

1. In the same app registration, select Certificates & secrets from the navigation menu.
2. Under Client secrets, select New client secret.
   
3. Configure the client secret:
   • Description: Enter a meaningful description (e.g., "Axero User Sync")
   • Expires: Choose an appropriate expiration period (recommended: 12 or 24 months)
   • Select Add
   
4. Critical: Immediately copy the client secret Value (not the Secret ID) and store it securely. This value will not be displayed again after you leave this page.
   

5.3 Configure User Syncing in Axero

1. Sign in to your Axero site as a Site Administrator.
2. Navigate to Control Panel > System > Single Sign-On.
3. On the Settings tab, configure the syncing options:
   • Check Enable user syncing
   • Check Sync profile pictures (if desired)
   
4. Enter the authentication credentials:
   • Application ID: Paste the Application (client) ID from step 5.1.3
   • Password: Paste the client secret value from step 5.2.4
   
5. Configure the sync schedule:
   • Syncing Day Interval: Set how often syncing occurs (e.g., daily = 1, weekly = 7)
   • UTC Syncing Start Time: Set the time when syncing should begin (in UTC)
6. Select Update to save the user syncing configuration.
   
7. Enable Microsoft Graph API support:
   • Navigate to Control Panel > System > System Properties
   • In the filter box, type "msgraph"
   • Locate the UseMSGraphAPI property and select Edit
   • Set the value to True and select Save
8. Test the user syncing configuration:
   • Ensure test users are assigned to the application in Entra ID (see Step 1.3 Configure User Assignment)
   • For manager synchronization: Verify that (1) users have managers assigned in Entra ID, (2) managers are assigned to the Entra ID enterprise application, (3) managers have existing accounts in Axero, and (4) Sync supervisors is enabled on the Data Mapping > Azure Active Directory tab
   • For profile picture sync: Ensure Sync profile pictures is enabled on the Settings tab and users have profile photos in Entra ID
   • Select Sync Now or wait for the next scheduled sync

Optional: Configure Role-Based Access Control

Axero can automatically assign and remove user roles based on attributes from Entra ID. This enables dynamic role management where user permissions are controlled centrally in Entra ID and synchronized to Axero during login.

6.1 Prepare Role Attributes in Entra ID

1. Define role attributes: Create or identify user attributes in Entra ID that will represent roles. These attributes should contain boolean values ("true" or "false") to indicate role membership.
2. Configure role claims:
   • In the Microsoft Entra admin center, navigate to Identity > Applications > Enterprise applications
   • Select your Axero SSO application
   • Select Single sign-on > Attributes & Claims and select Edit
3. Add role claims: For each role you want to manage:
   • Select Add new claim
   • Name: Enter a descriptive, space-free name (e.g., "isManager", "isHRAdmin")
   • Source attribute: Select the corresponding user attribute that contains the true/false value
   • Leave Namespace blank
   • Select Save
4. Repeat step 3 for each role you want to synchronize from Entra ID to Axero.

6.2 Configure Role Mapping in Axero

1. Create corresponding roles in Axero:
   • Navigate to Control Panel > People > Roles
   • Select Add User Role for each role you want to manage via SSO
   • Define each role with a meaningful Name and Description
   • Configure appropriate permissions for each role
   • Select Save
2. Configure role attribute mapping:
   • Navigate to Control Panel > System > Single Sign-On
   • Select the Data Mapping tab
   • Ensure Type is set to Azure Active Directory
3. Add role mappings: For each role claim configured in Entra ID:
   • Select Add to create a new mapping
   • Property name: Enter the exact claim name from step 6.1.3 (e.g., "isManager")
   • Field: Select Set User Role
   • Role: Select the corresponding Axero role from the dropdown
   • Select Save or continue adding more mappings
4. Select Update to save all role mapping configurations.
5. Test role assignment:
   • Ensure test users have appropriate role attribute values set in Entra ID
   • Have test users log in via SSO
   • Verify that roles are correctly assigned or removed in Axero based on the Entra ID attributes
   • Check user profiles in Axero to confirm role assignments

Additional Considerations

User Account Management

• Disabled Users: Microsoft Entra ID does not automatically communicate user account status changes to Axero via SAML. When users are disabled in Entra ID, you must manually deactivate their accounts in Axero to prevent access.
• User Deletion: Similarly, when users are deleted from Entra ID, their Axero accounts will remain active unless manually deactivated.
• Username Changes: If a user's username (UPN) changes in Entra ID, this may create a new user account in Axero rather than updating the existing one.

Security Best Practices

• Assignment Control: Use "Assignment required = Yes" to maintain strict control over who can access your Axero site via SSO.
• Regular Audits: Periodically review user assignments in Entra ID and active users in Axero to ensure alignment.
• Certificate Management: Monitor SAML certificate expiration dates and plan for certificate renewal to prevent service interruption.
• Client Secret Rotation: If using user syncing, establish a process for rotating client secrets before they expire.

Performance Considerations

• User Syncing Frequency: Balance sync frequency with system performance — daily syncing is typically sufficient for most organizations.
• Large Organizations: For organizations with thousands of users, consider the impact of frequent syncing operations on system resources.