Connect Microsoft Entra ID

Before you start

Choose one administrator and a small pilot group. Test the connection before requiring SSO for the wider organisation.

• An PortabilityLabs organisation already exists.
• You can verify the organisation’s sign-in domain.
• Your Entra administrator can create and configure an Enterprise Application. Microsoft lists Cloud Application Administrator, Application Administrator or service-principal ownership as suitable roles.
• You have one pilot user or group and a private browser window for testing.
• Your Entra security policy, including MFA and Conditional Access, is ready to apply to the application.

Configure SAML

1. 1

   Open the organisation setup link

   Request the link from PortabilityLabs, open it as the organisation administrator and verify the domain requested by the guided setup. The link is time-limited; request a replacement if it has expired.

2. 2

   Choose Microsoft Entra ID SAML

   The setup shows two values you will need: the Entity ID and Assertion Consumer Service (ACS) URL. Keep this window open.

3. 3

   Create the Entra enterprise application

   In the Microsoft Entra admin centre, go to Enterprise applications → New application → Create your own application. Choose the option for integrating another application that is not in the gallery, then select Single sign-on → SAML.

4. 4

   Enter the SAML endpoints

   Set Identifier (Entity ID) to the WorkOS Entity ID. Set Reply URL (ACS URL) to the WorkOS ACS URL. These values route the response to the correct PortabilityLabs organisation.

5. 5

   Confirm user claims

   Use the standard WorkOS claim mapping below. The pilot user must have values for the attributes your tenant sends.

   SAML claimEntra source

   …/emailaddressuser.mail

   …/givennameuser.givenname

   …/nameuser.userprincipalname

   …/surnameuser.surname
6. 6

   Assign a pilot user or group

   Set Assignment required to Yes when your access policy requires explicit assignment. Add only the pilot user or group first. Group-based assignment requires the relevant Entra licence, and nested group membership does not automatically cascade.

7. 7

   Connect the federation metadata

   Copy Entra’s App Federation Metadata URL into the WorkOS setup, then save the connection. This lets WorkOS obtain the signing certificate and identity-provider configuration without asking you to email certificate files.

Test, then enforce

1. 1

   Start from PortabilityLabs

   Use a private browser window and your normal PortabilityLabs sign-in route. Sign in with the pilot user and complete any Entra MFA or Conditional Access challenge.

2. 2

   Check the organisation

   Confirm that the user lands in the intended organisation and can see only the projects expected for their PortabilityLabs membership.

3. 3

   Test denial as well as success

   Try an unassigned user. They should be denied by Entra. A user who authenticates successfully but lacks an PortabilityLabs membership should still be denied product access.

4. 4

   Expand and enforce

   Assign the required users or groups. Ask PortabilityLabs to require SSO only after the pilot and recovery path have been confirmed.

Access, roles and offboarding

Removing an Entra assignment prevents a new SSO sign-in. For immediate offboarding, also remove or deactivate the person’s PortabilityLabs membership so application access does not depend on an existing browser session expiring. Automatic group-to-role mapping and directory-driven deprovisioning are not currently part of this SAML setup.

Does this give PortabilityLabs access to AWS?

No. Workforce sign-in and AWS discovery are separate trust boundaries. AWS discovery uses a separately approved, temporary role for the accounts and regions selected by the customer.

Need OIDC instead?

Entra OIDC is supported by the identity platform, but it requires an app registration, client ID, client secret and discovery endpoint, plus an agreed secret-rotation process. Contact us if your identity policy requires OIDC rather than SAML.

Troubleshooting