Before you begin
You will need:
The eTrack SSO module activated for your licence.
Administrator access to your eTrack system.
An Active Directory/Microsoft Entra administrator.
Your public eTrack HTTPS address, for example https://etrack.example.com.
A Microsoft Entra tenant containing the users who will sign in.
An Entra application registration.
The following values from that application:
Directory/tenant ID.
Application/client ID.
Client secret value.
Registered callback/redirect URI.
Identity architecture: the SSO module uses Microsoft Entra ID and OpenID Connect. It does not connect directly to an Active Directory domain controller using LDAP.
If users exist only in on-premises Active Directory, synchronise them to Microsoft Entra ID first using Microsoft Entra Connect or Cloud Sync. Microsoft describes this hybrid identity arrangement in its directory synchronisation guidance.
Part 1 — Information your AD administrator must provide
1. Confirm that users exist in Microsoft Entra ID
Users must be visible in the appropriate Microsoft Entra tenant. For on-premises AD:
Synchronise the required users to Entra.
Synchronise any AD groups that will control eTrack profiles or user groups.
Ensure each user has a valid email address or User Principal Name, such as [email protected].
Ideally, the user's Entra UPN should match their eTrack email address.
2. Register eTrack as an application
In the Microsoft Entra admin centre:
Open Entra ID > App registrations.
Select New registration.
Enter a name such as eTrack SSO.
Select Accounts in this organisational directory only.
Register the application.
From the application's Overview page, record the Directory (tenant) ID and the Application (client) ID.
3. Add the callback URI
The callback shown on the eTrack SSO settings page must be registered in Entra exactly.
Open Authentication.
Select Add a platform.
Select Web.
Enter the exact eTrack callback URI, normally: https://your-etrack-address/sso-callback.
Save the configuration.
Exact match required: the scheme, hostname, port, and path must match exactly. For example, etrack.example.com and www.etrack.example.com are different callback hosts.
4. Create a client secret
Open Certificates & secrets.
Select New client secret.
Enter a description and expiry period.
Copy the secret's Value immediately.
Secret handling: do not copy the Secret ID — eTrack requires the client secret value. Record the expiry date and arrange to replace the secret before it expires.
5. Configure group claims if using group mappings
This is optional if everyone will receive the same eTrack profile. To use AD/Entra groups to assign eTrack profiles or user groups:
Open the application's Token configuration.
Select Add groups claim.
Choose Groups assigned to the application (recommended for controlled access and larger organisations) or Security groups (includes the user's security-group memberships).
Ensure the claim is included in the ID token.
Save.
By default, Entra normally sends group object IDs. This is acceptable because eTrack can map those exact IDs.
If friendly group names should appear under Groups Seen, grant the application the Microsoft Graph Application permission Directory.Read.All and provide administrator consent. This lets eTrack resolve group IDs using Microsoft Graph. Without it, authentication still works, but groups may be displayed as IDs.
Group-overage limit: users with more than 200 group memberships may not receive a normal groups claim. eTrack does not retrieve memberships from Entra's group-overage claim, so Groups assigned to the application is the safer option.
Part 2 — Configure the Single Sign-On page
Open Settings > Single Sign-On.
Provider and defaults
Identity provider: Microsoft Entra ID
Enable Single Sign-On Login: turn on once testing is complete.
Create users on first SSO login: enable if eTrack should automatically create users.
Fallback eTrack profile: select the safest standard profile for users without a matching group.
Callback/redirect URI: the exact HTTPS URI registered in Entra.
Allowed email domains: approved domains, such as example.com.
Leave Allowed email domains blank only if every account accepted by the Entra application should be allowed. Enter multiple domains with commas, for example: example.com,example.org.
Application credentials
Tenant/directory ID: the Directory (tenant) ID from Microsoft.
Application/client ID: the Application (client) ID from Microsoft.
Client secret value: the secret value, not its ID.
Editing an existing setup: leave the client-secret field blank to retain the saved encrypted secret.
User provisioning
Choose one approach.
Automatically create users — enable Create users on first SSO login. On the first successful login, eTrack creates an active web user using information from the Entra token and assigns the fallback or mapped profile.
Use existing eTrack users — leave automatic creation disabled. Before users sign in:
Create or enable their eTrack account.
Enable web login.
Set their eTrack email address or username to the same email/UPN returned by Entra.
Matching is case-insensitive. eTrack matches the Entra identity against the existing user's email address or username.
Part 3 — Configure AD group mappings
Group mapping is optional.
Profile assignment rules
Use these rules when an AD/Entra group should control the user's eTrack permission profile. For each rule:
Select Add profile mapping.
Enter or select the exact value from Groups Seen.
Select the corresponding eTrack profile.
Save.
The first matching rule determines the user's profile. If mappings exist but no rule matches, eTrack applies the fallback profile.
User group sync rules
Use these rules when an AD/Entra group should add the user to an eTrack user group. For each rule:
Select Add user group mapping.
Enter or select the exact group value.
Select the corresponding eTrack user group.
Save.
Mapped membership is synchronised during login:
A matching claim adds the user to the mapped eTrack group.
Removing that claim removes the user from that mapped eTrack group.
Unrelated manual eTrack group memberships are left unchanged.
Finding the group values
Initially, Groups Seen may be empty.
Save the basic configuration.
Sign in once using a test user who belongs to the required AD groups.
Return to Settings > Single Sign-On.
Review Groups Seen.
Create mappings using the exact displayed value.
Sign out and test again.
Matching is case-insensitive, but copying the displayed value is recommended.
Part 4 — Test before enabling it for everyone
Use a non-administrator test account. Confirm that:
The login page displays Sign in with Microsoft.
Microsoft accepts the account.
The user returns to the same eTrack hostname used in the callback URI.
The correct existing user is matched, or a new user is created.
The fallback or mapped eTrack profile is correct.
AD group mappings apply the correct eTrack user groups.
A disallowed email domain is rejected.
Normal eTrack administrator access remains available during testing.
Least-privilege warning: do not assign a highly privileged fallback profile. A missing or incorrectly configured group claim could otherwise give users excessive access.
Common problems
SSO button does not appear — SSO module or SSO Enabled setting is off.
"SSO sign-in is not configured" — missing tenant ID, client ID, client secret, or module activation.
State validation failed — login hostname and callback hostname do not match exactly.
Redirect URI error from Microsoft — Entra Web redirect URI differs from the SSO page.
User not found — auto-creation is off and email/username does not match the Entra UPN.
Account domain is not allowed — UPN/email suffix is missing from Allowed email domains.
Groups Seen is empty — Entra is not sending a groups or roles claim.
Group names appear as GUIDs — normal Entra behaviour; Graph permission is missing or not consented.
Wrong profile assigned — first matching rule or fallback profile is incorrect.
User belongs to many AD groups — Entra group-overage limit has been reached.
Login stops after secret previously worked — client secret has expired.
If anything does not behave as described, contact the e-Track support team on 0121 647 2770 or [email protected]