---
title: "Microsoft Entra SAML SSO"
description: "Connect Microsoft Entra ID to OpenWork Cloud with SAML"
---

Use this guide when an organization wants members to sign in to OpenWork with
Microsoft Entra ID.

After SAML sign-in works, use
[Microsoft Entra SCIM provisioning](/cloud/scim-microsoft-entra) to synchronize
members and groups automatically.

## Before you start

You need:

- An OpenWork organization with the Enterprise SSO entitlement.
- Owner or admin access in that OpenWork organization.
- Admin access to a Microsoft Entra enterprise application.
- The final OpenWork auth origin, for example `https://app.openworklabs.com`.

## 1. Create the Entra enterprise app

In the Microsoft Azure portal, open **Microsoft Entra ID** and create a new
enterprise application for OpenWork. Choose **SAML** as the single sign-on
method.

## 2. Configure Basic SAML Configuration

In Entra, open **Single sign-on** and edit **Basic SAML Configuration**.

Set:

| Entra field | Value |
| --- | --- |
| Identifier (Entity ID) | The OpenWork auth origin, for example `https://app.openworklabs.com` |
| Reply URL (Assertion Consumer Service URL) | The ACS URL OpenWork shows after saving SAML, for example `https://app.openworklabs.com/api/auth/sso/saml2/sp/acs/openwork-sso-<org-id>` |
| Sign on URL | The org-specific OpenWork **Sign-in URL** shown after saving SAML, for example `https://app.openworklabs.com/sso/<org-slug>` |
| Relay State | Leave blank |

The Entity ID must be the OpenWork auth origin. Do not use the Entra tenant
identifier, `https://sts.windows.net/<tenant-id>/`, as the Entity ID.

OpenWork SAML connections are organization-scoped. If a user belongs to
multiple OpenWork organizations, the Entra app, ACS URL, and Sign-in URL select
which organization they are entering.

## 3. Configure SAML signing

Open **SAML Certificates** and edit the token signing certificate settings.

Set:

- **Signing Option**: `Sign SAML assertion`
- **Signing Algorithm**: `SHA-256`

OpenWork requires signed SAML assertions. If Entra signs only the response, the
callback fails with `saml_error` and `Invalid SAML response`.

After any certificate change, copy the active certificate again. Entra can
create or activate a new signing certificate while you are editing SAML
settings, and OpenWork must store the certificate that is currently active.

## 4. Copy Entra values into OpenWork

In OpenWork, open the organization dashboard, then **SSO**. Choose **SAML** and
enter:

| OpenWork field | Entra value |
| --- | --- |
| IdP Issuer URL | **Microsoft Entra Identifier**, for example `https://sts.windows.net/<tenant-id>/` |
| Domain | The Entra-managed email domain, for example `example.onmicrosoft.com` |
| SAML Entry Point | **Login URL**, for example `https://login.microsoftonline.com/<tenant-id>/saml2` |
| Audience URL | Leave blank so OpenWork uses the auth origin, unless support gives you a different audience |
| IdP Certificate | The active **Certificate (Base64)** from Entra |

Save the SSO connection. OpenWork then shows the generated ACS URL. Copy that
ACS URL back into Entra's **Reply URL** if it was not available before the first
save. Copy the OpenWork **Sign-in URL** into Entra's **Sign on URL** so the
Entra tile can launch the same organization-scoped flow.

## 5. Assign test users

In Entra, open the enterprise application's **Users and groups** page and assign
the users who should be allowed to sign in.

For external users, assign the guest identity shown by Entra, not only the
original external email address.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `AADSTS700016: Application with identifier 'https://app.openworklabs.com' was not found` | Entra's Entity ID does not match OpenWork's SAML issuer | Set **Identifier (Entity ID)** to the OpenWork auth origin |
| `/?error=saml_error&error_description=Invalid%20SAML%20response` | Entra is signing with a different certificate than the one saved in OpenWork, or assertions are not signed | Confirm **Signing Option** is `Sign SAML assertion`, then paste Entra's active **Certificate (Base64)** into OpenWork and save |
| `/?error=unsolicited_response&error_description=IdP-initiated+SSO+not+allowed` | The deployment is running an older OpenWork version that rejects IdP-initiated SAML | Upgrade OpenWork, or launch from the org-specific OpenWork **Sign-in URL** |
| User reaches Microsoft but cannot continue | The user is not assigned to the enterprise application | Add the user under **Users and groups** |
| Reply URL mismatch | Entra's Reply URL does not match the OpenWork ACS URL exactly | Copy the ACS URL from OpenWork and paste it into Entra |