SSO Onboarding Guide for Customer IT Teams

This guide is for the IT team connecting Microsoft Azure Entra ID to EvTrack with SAML 2.0. It covers what your team does in Azure, what you send to EvTrack, and how the two teams test and go live. Once it is done, your staff log in to EvTrack with their Microsoft accounts.

The server-side detail lives in the technical SAML guide. Using Active Directory Federation Services instead? See the AD FS guide.

SSO is configured on the EvTrack server, so it applies to a dedicated EvTrack system:

Hosted by EvTrack: the EvTrack team does all the server configuration. Your IT team completes the Azure steps and sends the required outputs.
On your own server: the same server settings are applied on your EvTrack server, normally by EvTrack support working with your IT team.

Before you start

Three things commonly hold an SSO project up, so settle them at kickoff:

There is no metadata file to import. EvTrack does not supply a Service Provider metadata XML file for Azure. You type the values into Azure by hand, as shown in Step 3.
Name a technical contact on each side. Exchange names and email addresses for your Entra administrator and the EvTrack SSO engineer, and let the two talk directly.
Create the EvTrack engineers’ test accounts in the first week. See Test accounts for EvTrack engineers.

Hold one joint configuration call with your Entra administrator and the EvTrack engineer on the line, rather than exchanging screenshots by email.

Responsibilities

Customer IT team	EvTrack team
Define the FQDN, Entity ID and Reply URL, and confirm them with EvTrack	Configure the SAML settings on the EvTrack server
Create the Enterprise Application in Azure Entra ID	Install the Azure certificate on the EvTrack server
Configure SAML SSO with the agreed values	Enable SSO and automatic account creation
Share the App Federation Metadata URL	Confirm a least-privilege default role for SSO users
Share the Base64 certificate (`entra.cer`)	Coordinate testing and go-live
Provide a SAML signing key and certificate from your certificate team
Assign users and groups to the EvTrack application
Allow outbound HTTPS to the EvTrack server
Take part in SSO testing

Prerequisites

Azure Portal access with the Global Administrator or Application Administrator role
Azure Entra ID licensed for Enterprise Applications
Firewall rules allowing outbound HTTPS (TCP/443) to the EvTrack server
A list of the Azure users or groups that need access to EvTrack

Settle these three values and confirm them with EvTrack in writing. The same values go into Azure and onto the EvTrack server:

Value	Example
EvTrack FQDN	`evtrack.company.com`
Entity ID	`evtrack-visitor-management`
Reply URL (ACS URL)	`https://evtrack.company.com/login/saml2/sso/entra`

Azure Entra ID configuration

Step 1: Create the Enterprise Application

Go to Azure Portal → Microsoft Entra ID → Enterprise applications.
Click New application → Create your own application.
Name it EvTrack Visitor Management.
Select Integrate any other application you don’t find in the gallery (Non-gallery).
Click Create.

Step 2: Select SAML

Open the new application and click Single sign-on in the left menu.
Select SAML as the method.
Click Edit under Basic SAML Configuration.

Step 3: Enter the Basic SAML Configuration

Enter these values by hand, replacing FQDN with the domain you agreed with EvTrack, then click Save.

Field	Value
Identifier (Entity ID)	`evtrack-visitor-management`
Reply URL (Assertion Consumer Service URL)	`https://FQDN/login/saml2/sso/entra`
Sign on URL (optional)	Leave blank
Relay State (optional)	Leave blank

The Entity ID and Reply URL are case-sensitive and must match EvTrack exactly. Copy and paste them rather than typing them from memory. Leave Attributes & Claims at the Azure defaults: EvTrack reads the user’s name, email address and Name ID from them.

Step 4: Copy the metadata URL and download the certificate

In the SAML Certificates section:

Copy the App Federation Metadata Url. It looks like this:

https://login.microsoftonline.com/{tenant-id}/federationmetadata/2007-06/federationmetadata.xml?appid={app-id}

Download Certificate (Base64) and rename the file entra.cer.

Step 5: Assign users and groups

Click Users and groups in the application’s left menu.
Click Add user/group.
Select the Azure users or groups who should have access to EvTrack.
Click Assign.

Only people assigned here can log in, as long as Assignment required? under the application’s Properties is set to Yes. Azure refuses anyone else with error AADSTS50105. Assigning an Azure group is easier to maintain than assigning individuals.

Automatic account creation lets every assigned user into EvTrack, so decide who belongs in this list before you go live. If contractor or external accounts should not reach EvTrack, leave them out of the assigned groups.

Step 6: Prepare the SAML signing key and certificate

EvTrack signs single logout requests with a key and certificate that your certificate team provides. EvTrack does not generate this pair for a customer deployment.

Private key: PEM format, unencrypted PKCS#8.
Certificate: PEM format, Base64-encoded with BEGIN and END markers.

Upload the certificate to Azure under Single sign-on → SAML Certificates → Verification certificates.

Required outputs

Send these items to EvTrack through your project channel:

#	Item	Notes
1	App Federation Metadata URL	The full URL from Step 4
2	`entra.cer`	The Base64 certificate from Step 4. Send the file itself, not a screenshot
3	SAML signing private key	From Step 6. Send it through a secure channel your security team approves, never by plain email
4	SAML signing certificate	From Step 6. Also uploaded to Azure under Verification certificates

EvTrack confirms receipt, then completes the server configuration. EvTrack does not send you an XML metadata file in return.

What EvTrack configures

No action is needed from your IT team for this section. For reference, the server settings are:

evtrack.security.config.sso.enable=true
evtrack.security.config.sso.auto-provision-new-user=true
evtrack.security.config.sso.auto-update-entity-username=true
spring.security.saml2.relyingparty.registration.entra.entity-id=evtrack-visitor-management
spring.security.saml2.relyingparty.registration.entra.assertingparty.metadata-uri=<App Federation Metadata URL>
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].private-key-location=<key file>
spring.security.saml2.relyingparty.registration.entra.signing.credentials[0].certificate-location=<certificate file>
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.url=<Azure logout URL>
spring.security.saml2.relyingparty.registration.entra.assertingparty.singlelogout.binding=REDIRECT
spring.security.saml2.relyingparty.registration.entra.singlelogout.response-url={baseUrl}/logout/saml2/slo

These settings give you:

Automatic account creation: an assigned user who has no EvTrack account gets one at first login.
Username updates: when no EvTrack username matches the login, EvTrack looks for a user with the same email address and updates that user’s username and name from Azure.
Single logout: logging out of EvTrack also ends the Microsoft session.

Turning SSO on also turns off EvTrack’s own login form and password reset, for administrators too. Before go-live, check that each EvTrack administrator’s account has the same email address as their Microsoft account, so they keep their access.

Who can log in, and what they can do

These are two separate decisions:

Who can log in is decided in Azure, by the assignment in Step 5.
What they can do is decided in EvTrack, by the user’s role.

EvTrack does not turn Azure groups into EvTrack permissions. Every account created through SSO gets the one role marked Is Default under Roles. On a new system that is the Hosts role, who can invite and manage only their own visitors.

Keep the default role at the lowest level of access anyone needs. After someone’s first login, an EvTrack administrator edits their account and gives them a higher role if they need one, for example a receptionist or a security officer. Agree before go-live who needs a higher role.

The default role cannot be the administrator role or a role with access to personal data. If an older system still has such a role as its default, EvTrack creates new SSO accounts with no role at all, and an administrator must give each one a role. People who already have an EvTrack account keep the role they have.

Test accounts for EvTrack engineers

EvTrack engineers cannot reproduce a login problem without an account in your Azure directory. Create Guest (B2B) accounts for two EvTrack engineers at kickoff. Each guest must do all three of these:

Accept the Azure invitation.
Enrol in MFA.
Be assigned to the EvTrack Enterprise Application, as in Step 5.

An invitation alone is not enough. A guest who has not been assigned is refused with AADSTS50105, the same as anyone else.

Testing

Run these tests with a designated test user once EvTrack confirms the server is ready. Book the session with EvTrack so the engineer can watch the server logs.

Test 1: Login

Open your EvTrack URL in a browser.
Confirm that EvTrack sends you straight to the Microsoft login page.
Log in with an Azure account assigned to the application.
Confirm that you return to EvTrack logged in.

EvTrack shows its own page, with a Microsoft-branded login button, only after a failed login or an unconfirmed logout.

Test 2: Automatic account creation

Log in with an assigned user who has never used EvTrack.
Confirm that the user appears in EvTrack with the correct name and email address, and holds the default role.

Test 3: Single logout

Log in, then click Logout in EvTrack.
Confirm that you are also logged out of Microsoft.

Test 4: Unassigned user

Try to log in with an Azure account that is not assigned to the application.
Confirm that Azure refuses access.

Implementation checklist

Phase 1: Azure Entra ID configuration (customer IT)

Phase 2: EvTrack server configuration (EvTrack)

Receipt of all outputs confirmed
SAML configuration applied to the EvTrack server
SSO and automatic account creation enabled
Least-privilege default role agreed and marked Is Default
Administrator accounts checked against their Microsoft email addresses
Users who need a higher role identified for an upgrade after first login
SSO confirmed ready for testing

Phase 3: Testing and go-live (both teams)

Assigned user logs in
New user created at first login, with the default role
Single logout works
Unassigned user refused by Azure
Higher roles given to the users who need them
SSO confirmed for production rollout

Troubleshooting

What you see	Likely cause	Fix
`AADSTS50011`: the reply URL does not match	The Reply URL in Azure differs from the one on the EvTrack server	Set the Reply URL exactly as agreed. It uses the exact FQDN and ends `/login/saml2/sso/entra`
`AADSTS50105`: the user is not assigned to a role for the application	The user is not assigned to the Enterprise Application	Add the user or their group under Users and groups. For an Azure group, check that the user is a member of it
`AADSTS700016`: application not found	The Entity ID in Azure differs from the one on the EvTrack server	Check that both are `evtrack-visitor-management`, or the value you agreed. The match is case-sensitive
EvTrack shows “Authentication failed. SAML authentication could not be completed.”	Entity ID mismatch, an out-of-date certificate, or the server clock is wrong	Send EvTrack the time of the attempt so the engineer can read the server log
EvTrack shows “No user profile found.”	Automatic account creation is off and the user has no EvTrack account	Ask EvTrack to turn automatic account creation on, or have an administrator add the user
EvTrack shows “Access restricted.”	The EvTrack account is disabled, expired or not yet active	An EvTrack administrator fixes the account. See the login troubleshooting page
EvTrack still shows a username and password form	SSO is not enabled on the server	Ask EvTrack to enable SSO
Single logout does not complete	The signing key or certificate is missing, or the certificate is not in Azure	Confirm that EvTrack has both files and the certificate is under Verification certificates
The login times out	A firewall is blocking HTTPS	Allow outbound HTTPS to `login.microsoftonline.com` and the EvTrack server

For any Azure error, open Azure Portal → Microsoft Entra ID → Sign-in logs and filter by the application EvTrack Visitor Management.

Support

Report SSO problems to support@evtrack.com, or through your system integrator. Include:

The Azure error code and correlation ID
The affected user’s email address
The date and time of the failed attempt
A screenshot of the browser error

Certificate renewal

Azure SAML certificates expire. Before yours does, generate a new certificate in Azure and send the new entra.cer to EvTrack, who will schedule the change so that logins are not interrupted. Your SAML signing certificate has its own expiry date, so plan for it the same way.