How to Set Up Microsoft Entra ID SSO and SCIM Provisioning for OpenWork

To configure Microsoft Entra ID SSO and SCIM provisioning for OpenWork, create an Entra ID enterprise application for SAML authentication, copy the IdP metadata into OpenWork's SSO settings, then generate a SCIM connector in OpenWork and configure Entra ID's automatic provisioning with the provided endpoint and bearer token.

OpenWork (from the repository different-ai/openwork) supports enterprise-grade identity management through native Microsoft Entra ID integration. This implementation combines SAML 2.0 for single sign-on with SCIM 2.0 for automated user lifecycle management, allowing organizations to centralize authentication and provisioning within their existing Entra ID infrastructure.

Architecture Overview

OpenWork's Microsoft Entra ID integration operates through two distinct but complementary protocols. The SAML component handles authentication by validating signed assertions from Entra ID, while the SCIM component exposes a REST API endpoint that Entra ID calls to provision, update, and de-provision users and groups.

The system distinguishes between synthetic and production environments. For local development, OpenWork includes a mock server that synthetically emulates Entra ID OAuth flows, but production deployments must connect to the actual Microsoft Entra ID endpoints. According to the enterprise-mcp-mock-server README, this mock server provides "Entra-shaped" responses for testing only and should never be used for production SSO configurations.

OpenWork validates Entra ID tenant identifiers using helper functions like normalizeEntraTenantId and isMicrosoftEntraManagedDomain. These utilities ensure consistent handling of tenant URLs and guard against malformed issuer strings, as demonstrated in the test suites sso-entra-domain.test.ts and oauth-tenant.test.ts.

Configuring SAML Single Sign-On

Create the Entra ID Enterprise Application

Begin by creating a new Enterprise Application in the Microsoft Entra ID admin center. Select "Create your own application" and choose "Integrate any other application you don't find in the gallery." Configure the single sign-on method as SAML.

Within the SAML configuration, set the following values:

• Identifier (Entity ID): Use the value provided by OpenWork in the SSO settings page
• Reply URL (Assertion Consumer Service URL): The ACS URL generated by OpenWork after initial configuration
• Sign on URL: Your OpenWork instance URL (e.g., https://app.openworklabs.com)

Download the SAML signing certificate (Base64 format) and copy the Login URL and Microsoft Entra Identifier values. The complete setup instructions are documented in packages/docs/cloud/sso-microsoft-entra.mdx.

Configure OpenWork SAML Settings

Navigate to your OpenWork organization settings and enable SAML SSO. Paste the Microsoft Entra Identifier into the Entity ID field and the Login URL into the SSO URL field. Upload the certificate file you downloaded from Entra ID.

OpenWork validates the SAML metadata and generates a unique ACS URL specific to your organization. Copy this ACS URL back into the Entra ID enterprise application's Reply URL field to complete the trust relationship. The microsoft-365-dialog.tsx component in the OpenWork dashboard surfaces these exact fields to guide administrators through the copy-paste workflow.

Enabling SCIM User Provisioning

Generate a SCIM Connector in OpenWork

After configuring SAML, navigate to the SCIM provisioning section in OpenWork settings. Create a new SCIM connector to generate the provisioning endpoint and authentication token. The system exposes the SCIM API at /api/auth/scim/v2 relative to your OpenWork base URL.

The connector creation returns two critical values:

1. Base URL: https://app.openworklabs.com/api/auth/scim/v2/
2. Bearer Token: A secret token displayed only once during creation

Store the bearer token securely, as OpenWork does not display it again after the initial creation. These values are required to configure the automatic provisioning in Entra ID, as detailed in packages/docs/cloud/scim-microsoft-entra.mdx.

Configure Entra ID Automatic Provisioning

In your Entra ID enterprise application, navigate to the Provisioning blade and set the mode to Automatic. Enter the SCIM values:

• Tenant URL: The Base URL from your OpenWork SCIM connector
• Secret Token: The Bearer Token from your OpenWork SCIM connector

Click "Test Connection" to verify that Entra ID can authenticate to the OpenWork SCIM endpoint. Once successful, configure the mapping attributes to synchronize user properties like userName, emails, and name. You can optionally enable group synchronization to provision OpenWork teams that mirror your Entra ID security groups.

Code Examples and API Integration

Creating a SCIM Connector via API

You can programmatically create SCIM connectors using the OpenWork REST API:

curl -X POST "https://api.openworklabs.com/v1/orgs/<ORG_SLUG>/scim/connectors" \
  -H "Authorization: Bearer <ADMIN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "entra-scim-connector",
    "description": "Microsoft Entra SCIM provisioning",
    "enabled": true
  }'

The response includes the base URL and bearer token:

{
  "baseUrl": "https://app.openworklabs.com/api/auth/scim/v2/",
  "bearerToken": "s3cr3t-t0k3n-generated-once-only"
}

Testing the SCIM Endpoint

Verify connectivity by listing users through the SCIM endpoint:

curl -X GET "https://app.openworklabs.com/api/auth/scim/v2/Users" \
  -H "Authorization: Bearer s3cr3t-t0k3n-generated-once-only" \
  -H "Accept: application/scim+json"

A successful response returns a SCIM 2.0 ListResponse object containing the provisioned users.

Sample SCIM Patch Operation

When Entra ID updates group memberships, it sends PATCH requests like the following:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        { "value": "user-uuid-from-openwork" }
      ]
    }
  ]
}

OpenWork's SCIM endpoint processes these operations to maintain synchronized team memberships.

Summary

• OpenWork supports Microsoft Entra ID through SAML 2.0 for authentication and SCIM 2.0 for provisioning, as implemented in the different-ai/openwork repository.
• The integration requires creating an Entra ID enterprise application, exchanging SAML metadata, and configuring the ACS URL in both systems.
• SCIM provisioning requires generating a connector in OpenWork to obtain a base URL and bearer token, then configuring Entra ID's automatic provisioning with these credentials.
• Helper functions like isMicrosoftEntraManagedDomain and normalizeEntraTenantId ensure robust tenant validation according to the source code in ee/apps/den-api/test/.
• The microsoft-365-dialog.tsx component provides the UI workflow for administrators configuring these settings.

Frequently Asked Questions

What is the difference between the synthetic Entra ID mock server and production?

The synthetic Entra ID mock server, located in packages/enterprise-mcp-mock-server, emulates OAuth and SAML responses for local development and testing purposes only. It generates "Entra-shaped" responses without connecting to Microsoft's actual services. Production deployments must use the real Microsoft Entra ID endpoints to ensure valid authentication and security token validation.

Where does OpenWork store the SAML metadata and SCIM tokens?

OpenWork stores SAML metadata (Entity ID, ACS URLs, and X.509 certificates) in the organization's SSO configuration within the database. SCIM bearer tokens are hashed using cryptographic functions before storage; only the hashed value is retained, while the plain-text token displays only once during connector creation. This security measure prevents token exposure even if the database is compromised.

How does OpenWork handle Entra ID tenant validation?

OpenWork validates Entra ID tenants through utility functions defined in the test files sso-entra-domain.test.ts and oauth-tenant.test.ts. The normalizeEntraTenantId function standardizes tenant identifier formats, while isMicrosoftEntraManagedDomain verifies that issuer URLs match expected Entra ID patterns, preventing spoofing attempts from unauthorized identity providers.

Can I provision OpenWork teams using Entra ID security groups?

Yes. When you enable group synchronization in the Entra ID provisioning configuration, Entra ID sends SCIM requests to create and update Group resources at the OpenWork /api/auth/scim/v2/Groups endpoint. OpenWork maps these SCIM groups to internal team entities, allowing you to manage team membership centrally within Entra ID while maintaining automatic synchronization with OpenWork's access controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}