Single Sign-On with Microsoft Entra ID

This guide connects Microsoft Entra ID to Workprentice for single sign-on and directory provisioning. You need to be an owner of the Workprentice organization and able to manage enterprise applications in Entra, and your email domain must already be verified by DNS.

Keep two tabs open: Organization settings → Single sign-on in Workprentice, with Microsoft Entra ID chosen at the top, and the Microsoft Entra admin center. The steps follow the admin center as Microsoft’s documentation describes it. Microsoft moves these menus from time to time, so where a label differs, go by the field names in the tables.

Single sign-on

Create the application in Entra

1. In the Microsoft Entra admin center, open Enterprise applications and choose New application.

2. Choose Create your own application, name it Workprentice, select Integrate any other application you don’t find in the gallery (Non-gallery), and choose Create.

3. In the new application, open Single sign-on and choose SAML.

4. Edit Basic SAML Configuration and fill in these fields from the Workprentice page:

   Entra field	Value from Workprentice
   Identifier (Entity ID)	Audience
   Reply URL (Assertion Consumer Service URL)	Single sign-on URL
   Sign on URL	Start URL (optional)

5. Save.

Check the email claim

Workprentice needs each person’s email address. Entra’s default claims already include emailaddress, taken from user.mail, and Workprentice reads it, so there is usually nothing to change under Attributes & Claims.

A person with no mail value has no email claim, and Entra’s default name ID is the user principal name. If some of your people have no mailbox, or their user principal name is not their email address, edit Unique User Identifier (Name ID) to an attribute that holds the address they should sign in with. Decide this before anyone signs in: the name ID is what ties a person to their account from their first sign-in on, and changing it later refuses their next one.

Leave token encryption off. Entra signs the assertion by default, which is what Workprentice expects.

Bring Entra’s details back

On the same Single sign-on page:

Entra shows	Where	Workprentice field
Certificate (Base64)	SAML Certificates, download	Signing certificate: open the file in a text editor and paste its contents
Login URL	Set up Workprentice	Sign-in URL
Microsoft Entra Identifier	Set up Workprentice	Issuer

Save in Workprentice.

Assign people and test

Under Users and groups, assign the people or groups who should have access. Then open a private browser window, go to the Workprentice sign-in page, enter your work email, and choose Continue with single sign-on.

When it works, an owner signed in through Entra can require single sign-on.

Entra’s signing certificate expires, three years after creation by default. Before it does, create the new certificate in Entra, paste it after the old one in Workprentice, save, and then make it active in Entra.

Directory provisioning

Connect provisioning

1. In Workprentice, under Directory provisioning, choose Turn on directory provisioning, then create a token named Entra. Copy the token now; it is shown once.

2. In the same enterprise application in Entra, open Provisioning and set Provisioning Mode to Automatic.

3. Under Admin Credentials, fill in:

   Entra field	Value from Workprentice
   Tenant URL	SCIM endpoint
   Secret Token	The token

4. Choose Test Connection, then Save.

Choose what Entra sends

Under Mappings, leave both Provision Microsoft Entra ID Users and Provision Microsoft Entra ID Groups enabled, with create, update, and delete allowed. The default attribute mappings work: Entra sends the user principal name as userName and mail as the work email, and Workprentice matches people by the email.

Under Settings, set Scope to Sync only assigned users and groups, so the directory holds the people you assigned and no one else. Consider turning on Prevent accidental deletion; Workprentice applies whatever Entra sends, with no limit of its own.

Start it

Set Provisioning Status to On and save. Entra runs an initial cycle and then sends changes about every 40 minutes, so a deactivation in Entra can take that long to remove someone from Workprentice. Provision on demand sends one person or group immediately, which is the quickest way to test and to offboard someone urgently.

Groups you assigned to the application appear in Workprentice under Group access, where you map each to a workspace and a role.

If something does not work

• Sign-in fails with “could not be completed”. Check that the certificate in Workprentice is the active one in Entra and has not expired, and that Identifier and Reply URL match the Workprentice page exactly.
• Someone signs in at Microsoft but is refused. Check that they have a mail value at a domain you have verified. With provisioning on, they must also be assigned to the application and have been through a provisioning cycle.
• Test Connection fails. Create a fresh token and paste it again; a token is shown once and cannot be recovered.
• A removed person is still a member. Check Provisioning logs in Entra for the request. An organization owner is never removed this way.