Microsoft Entra Single Sign-On Setup Guide

Connect ProVisit to Microsoft Entra ID so your internal users can sign in using their Microsoft work accounts.

ProVisit uses your organisation’s own app registration. Your organisation manages the application, client secret, Microsoft access policies and any Conditional Access requirements.

Before you start

You will need:

• Permission to create and manage Microsoft Entra app registrations.

• An administrator who can grant consent for the required permissions.

• ProVisit administrator access with permission to edit settings.

• The Entra connector and SSO features enabled for your ProVisit site.

• Your organisation’s trusted email domain, such as example.com.

Send your Directory (tenant) ID to help@provisit.co.uk so ProVisit support can assign it to your site. The tenant ID entered in ProVisit must match this assignment.

Do not email your client secret or password to support.

Before enforcing SSO, make sure your internal users are linked to their Microsoft Entra identities and have the required ProVisit access. Configure and test an emergency access account first.

1. Create an app registration

1. Sign in to the Microsoft Entra admin centre.

2. Open Microsoft Entra ID → App registrations.

3. Select New registration.

4. Enter a name, such as ProVisit SSO.

5. Select Accounts in this organisational directory only.

6. Under Redirect URI, select the Web platform.

7. Enter your ProVisit callback URL:

https://your-provisit-domain.com/auth/entra/callback

Replace https://your-provisit-domain.com with your actual ProVisit site address.

8. Select Register.

The redirect URI must exactly match your ProVisit site, including HTTPS, the subdomain and the callback path. Do not add a trailing slash.

2. Copy the application and tenant IDs

Open the app registration’s overview page and copy:

• Application (client) ID

• Directory (tenant) ID

You will enter both values in ProVisit.

The Directory (tenant) ID must also match the ID assigned to your site by ProVisit support.

3. Create a client secret

1. In the app registration, open Certificates & secrets.

2. Select New client secret.

3. Enter a description, such as ProVisit integration.

4. Choose an expiry period that meets your organisation’s policy.

5. Select Add.

6. Copy the secret’s Value immediately.

Copy the secret value, not the secret ID. Microsoft only displays the value when the secret is created.

Store it securely and arrange to replace it before it expires. An expired secret can prevent SSO and group synchronisation from working.

4. Configure API permissions

Open API permissions in the app registration.

Single sign-on

Add the following Microsoft Graph permission:

ProVisit also requests the OpenID Connect scopes openid, profile and email during sign-in.

Your organisation’s Microsoft policies may require administrator consent.

Group synchronisation

If you also use Entra group synchronisation, add these Microsoft Graph application permissions:

Application permissions require administrator consent.

SSO and group synchronisation perform different operations. Test each feature separately after configuring the integration.

5. Configure ProVisit

1. Sign in to ProVisit as an administrator.

2. Go to Settings → Integrations → Microsoft Entra ID.

3. Enter:

   • Tenant ID

   • Client ID

   • Client Secret

   • Secret Expiry, if available

4. Enter your trusted SSO domain, such as example.com.

5. Leave Enforce SSO for internal users turned off while preparing and testing user access.

6. Select Save & Validate.

Enter the domain only, without @, https:// or a path. ProVisit currently supports one trusted SSO domain.

ProVisit checks the credentials before saving them. Successful validation does not confirm that every user is ready for SSO or that group-sync permissions are complete.

If the integration options are missing, contact ProVisit support.

6. Prepare users for SSO

A successful Microsoft sign-in does not automatically create a ProVisit account or link an existing account by email.

To use SSO, a user must:

• Have an internal ProVisit account.

• Be active and have accepted their ProVisit account.

• Be linked to the correct Microsoft Entra object ID.

• Have a ProVisit role, location access and application access.

• Be a Member of the configured Entra tenant.

• Have an Entra email address or user principal name using the trusted domain.

Microsoft Entra Guest accounts are not supported by this SSO flow.

Linking existing accounts

Where group synchronisation is enabled, sync can link an eligible existing internal account using matching email or user principal name information. Conflicting matches are skipped for review.

Run the configured sync and confirm that the user is linked before testing SSO. Contact ProVisit support if an account remains unlinked.

Once linked, ProVisit identifies the account by its Entra object ID. The email returned by Microsoft does not need to exactly match the local ProVisit email.

7. Configure emergency access

A breakglass account provides local password access when Microsoft sign-in or the connector is unavailable.

To designate an account:

1. Go to Settings → Users.

2. Select the internal user.

3. Open Emergency access.

4. Select Enable breakglass.

5. Confirm the change.

The account must be active, accepted and have a local password. Only administrators can change breakglass status, and changes are audited.

Breakglass accounts:

• Use a local password regardless of SSO enforcement.

• Do not sign in through the Microsoft SSO flow.

• Remain subject to ProVisit’s local two-factor authentication requirements.

Test emergency access before enabling SSO enforcement.

8. Test sign-in and enable enforcement

1. Keep your current administrator session open.

2. Open a private browser window.

3. Visit your ProVisit login page.

4. Enter a linked internal user’s email address on the trusted domain.

5. Complete Microsoft sign-in.

6. Complete ProVisit two-factor authentication if prompted.

7. Confirm that the user can access the expected application and locations.

8. Separately test your breakglass account using its local password.

Once the required internal users are linked and tested, return to the Entra integration settings and enable Enforce SSO for internal users.

What enforcement changes

Enforcement blocks local password access for internal users even when their email is outside the trusted domain, except for breakglass accounts.

Turning enforcement off does not restore password access for Entra-linked users.

Two-factor authentication

Microsoft authentication does not replace ProVisit’s local two-factor requirements.

• Users already enrolled in ProVisit two-factor authentication must complete its challenge after Microsoft sign-in.

• Users required to enrol by your ProVisit policy are directed to setup.

• Your organisation’s Microsoft MFA and Conditional Access policies may also apply during Microsoft sign-in.

Users may therefore encounter both Microsoft and ProVisit authentication prompts.

Rotate the client secret

Replace the secret before its expiry date:

1. Create a new client secret in Microsoft Entra.

2. Copy the new secret’s Value.

3. In ProVisit, open Settings → Integrations → Microsoft Entra ID.

4. Select Update Credentials.

5. Enter the new secret and update the expiry date.

6. Save and validate the settings.

7. Test SSO and, if used, group synchronisation.

8. Remove the old secret from Microsoft Entra after confirming the new one works.

Troubleshooting

Credentials do not validate

Check that:

• The Tenant ID matches the tenant assigned to your ProVisit site.

• The Client ID belongs to the intended app registration.

• You copied the client secret’s value, not its ID.

• The secret has not expired.

If validation succeeds but sign-in or sync fails, check the permissions and consent required for that feature.

A user is still asked for a password

Check that:

• The Entra connector and SSO feature are available.

• The entered address uses the trusted domain.

• The user is an internal user.

• The user is linked to Entra, or SSO enforcement is enabled.

A breakglass account is expected to use a password.

A password prompt does not guarantee that password login is permitted. Entra-linked accounts cannot use a local password unless designated as breakglass accounts.

A user cannot sign in with SSO

Check that:

• The user’s ProVisit account is active and accepted.

• It is linked to the correct Entra object ID.

• The user has a role, location access and application access.

• The Microsoft account belongs to the configured tenant and is a Member.

• The Entra email or user principal name uses the trusted domain.

• The account is not designated as breakglass.

An exact match between local and Entra email addresses is not required once the account is linked.

Microsoft reports a redirect URI mismatch

Check the app registration’s Web redirect URI against:

https://your-provisit-domain.com/auth/entra/callback

Check HTTPS, the subdomain, the callback path and any trailing slash.

Group sync does not process anyone

Check that:

• Group synchronisation is enabled for your site.

• The connector is configured and active.

• At least one group mapping is active.

• The mapped groups contain the expected users.

• The application permissions have administrator consent.

Review the sync results for errors or skipped accounts.

A user receives SSO-001

Contact help@provisit.co.uk with:

• Your ProVisit site URL.

• The time of the failed attempt, including the time zone.

• The displayed error code.

Do not send passwords, client secrets or authentication tokens.