2026-09-02 01:05:41 +08:00
commit 04bac1f6e2
2200 changed files with 489415 additions and 0 deletions
@@ -0,0 +1,98 @@
---
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 |