99 lines
4.6 KiB
Plaintext
99 lines
4.6 KiB
Plaintext
---
|
|
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 |
|