Single Sign-On

Optimal Workforce supports enterprise single sign-on through Microsoft Entra ID using SAML. Once it is set up:

• Your IT team decides who can sign in, from Entra, using the normal user and group assignment they already use for other applications.
• Optimal Workforce appears in your users' My Apps portal.
• New users who sign in are attached to your organization automatically.

This page covers both halves: what your IT team does in Entra, and what your organization owner does in Optimal Workforce.

Before you begin

• You need an organization owner account in Optimal Workforce. Only owners can register an identity provider.
• You need someone with permission to create an Enterprise Application in your Entra tenant.
• Have both people available at the same time, or expect one round trip — each side needs a value from the other.

Step 1 — Collect the service provider values

Sign in as the organization owner and go to Manage Tenant → Single Sign-On (/home/organization/sso).

The page shows two values with copy buttons:

Copy both. Your IT team needs them for the next step.

Step 2 — Create the Enterprise Application in Entra

In the Microsoft Entra admin centre:

1. Go to Enterprise applications → New application → Create your own application, choose the non-gallery option, and give it a name your users will recognise (for example "Optimal Workforce").
2. Open Single sign-on and choose SAML.
3. In Basic SAML Configuration, set:
   • Identifier (Entity ID) — the value from step 1
   • Reply URL (ACS URL) — the value from step 1
4. Save.
5. Copy the App Federation Metadata Url from the SAML certificates section. It looks like https://login.microsoftonline.com/<tenant-id>/federationmetadata/2007-06/federationmetadata.xml.
6. Under Properties, set Assignment required to Yes.
7. Under Users and groups, assign the people and groups who should have access.

Step 3 — Register the provider in Optimal Workforce

Back on Manage Tenant → Single Sign-On, the owner enters:

• Email domain — for example contoso.com
• Entra SAML metadata URL — the federation metadata URL from step 2

Then choose Register provider.

The domain is how the platform decides which identity provider to send a user to. Someone signing in as jane@contoso.com is routed to the provider registered for contoso.com.

A domain can only be registered by one organization. If registration is rejected because the domain is already claimed, someone else in your company has probably already set it up.

Errors coming back from Entra — most often an unreachable or wrong metadata URL — are shown inline on the form.

Step 4 — Test with one user

Have an assigned user go to the sign-in page, choose Sign in with SSO, and enter their work email address. They should be redirected to Microsoft, sign in, and land in Optimal Workforce.

Confirm they can see the app tile at myapplications.microsoft.com.

How new users are provisioned

When a user signs in through Microsoft for the first time and their email domain matches an enabled registered domain, the platform automatically:

1. attaches their account to your organization, and
2. grants them the configured organization role, which is viewer by default.

Three things about this are worth being precise on:

• Only Microsoft sign-ins are provisioned. The platform checks that the user actually arrived through SAML SSO or Microsoft OAuth. Password sign-ups are never auto-joined to your organization, regardless of email domain.
• It fires on first creation only. Users who already existed before you registered the domain are not retroactively attached. Add them manually from Manage Tenant → Members.
• Viewer is read-only, and organization-only. An auto-provisioned user can see the organization roster and nothing else. They get no access to any team's caseload data until someone invites them into a team. See Teams and Members.

If provisioning cannot complete for some reason, the sign-in itself still succeeds — the account is created but is not attached to your organization. Add the person manually from Manage Tenant → Members.

So the normal flow for a new employee is: IT assigns them in Entra → they sign in → they appear in your organization as a viewer → an owner or admin elevates their organization role if needed, and a team owner invites them into the teams they work in.

Removing a provider

An owner can remove a registered provider from the same page. After removal, users from that domain can no longer sign in through SSO. Existing accounts and their team memberships are not deleted — they simply lose that sign-in route, so make sure the people who still need access have another way in before you remove it.

To remove one person's access without touching the provider, unassign them in Entra. That is the faster and more usual action.

Troubleshooting

More in Troubleshooting.