Skip to main content
Use this guide to let organization members sign in to OpenWork through an Okta application integration. It works for OpenWork Cloud and for a Helm deployment with a public HTTPS web origin. After SAML sign-in works, use Okta SCIM provisioning to synchronize members and groups.

​
Before you start

You need:
  • An OpenWork owner, or a member who can manage security configuration.
  • An Okta administrator who can create and assign application integrations.
  • Control of DNS for the email domain you will associate with the connection.
  • The final HTTPS OpenWork web origin, for example https://openwork.example.com.
Keep Require SSO for this organization off until an owner has completed a fresh SAML sign-in. Keep password access available as a recovery path during setup.
For a Helm deployment with separate web and API hosts, use the URLs OpenWork shows in Settings → SSO. Do not replace their host with the separate API origin. SAML uses the deployment’s configured auth origin, which is normally the public web origin when /api/auth is proxied through the web host.

​
1. Get the organization ID

In OpenWork, select the organization and open Settings → General. Copy the organization ID. OpenWork creates the SAML provider ID as:
The corresponding assertion consumer service URL is:
You can confirm the exact generated URL after saving the OpenWork connection.

​
2. Create the Okta SAML application

In the Okta Admin Console:
  1. Open Applications → Applications.
  2. Select Create App Integration.
  3. Choose SAML 2.0, then select Next.
  4. Set App name to OpenWork or another recognizable workspace name.
  5. Select Next.

​
3. Configure SAML in Okta

Under General, enter: Open Show Advanced Settings and confirm:
  • Response: Signed
  • Assertion Signature: Signed
  • Signature Algorithm: RSA-SHA256
  • Digest Algorithm: SHA256
  • Assertion Encryption: Unencrypted
OpenWork requires a signed assertion. Keep the Okta username and NameID equal to the stable work email that SCIM will later send as userName. Select Next, mark the integration as an internal application when appropriate, then select Finish.

​
4. Copy Okta values into OpenWork

In the Okta application’s Sign On tab, select View SAML setup instructions. Copy:
  • Identity Provider Single Sign-On URL
  • Identity Provider Issuer
  • X.509 Certificate, including the BEGIN CERTIFICATE and END CERTIFICATE lines
In OpenWork, open Settings → SSO, select SAML, and enter: Save the connection. Compare the generated ACS URL with Okta’s Single sign-on URL character for character. Also copy the generated OpenWork Sign-in URL; use this URL for the first test.

​
5. Verify the email domain

Select Request token under Domain verification. Create a DNS TXT record for the email domain: For example, provider openwork-sso-org_123 for example.com produces:
In a DNS console that automatically appends the zone, enter only _better-auth-token-<provider-id> in the name field. The token is valid for seven days. After the TXT record resolves publicly, select Verify domain in OpenWork and confirm the connection shows Domain verified: Yes.

​
6. Assign a test user in Okta

In the Okta application:
  1. Open Assignments.
  2. Select Assign → Assign to People.
  3. Assign one OpenWork owner or another controlled test user.
  4. Confirm the application username is that user’s stable work email.
Do not assign broad groups until the test user can complete the full flow.

​
7. Test SP-initiated sign-in

Open the organization-specific OpenWork Sign-in URL in a fresh browser session. Confirm that:
  1. OpenWork redirects to the expected Okta tenant.
  2. Okta authenticates the assigned user.
  3. Okta posts the assertion to the generated OpenWork ACS URL.
  4. OpenWork returns the user to the intended organization.
  5. The member identity in OpenWork uses the same email that Okta sent as NameID.
Only after this succeeds should you configure SCIM or enable Require SSO for this organization.

​
Troubleshooting