Introduction
We are using WorkOS to support SAML SSO for Dotwork. You'll receive an email from WorkOS with an Admin Portal link to configure your Identity Provider (IdP). If you are unable to receive the email, we can send a direct link instead.
In the Admin Portal, WorkOS will provide the Service Provider (SP) details you'll need to enter in your IdP (Entity ID / Issuer, ACS URL, etc.).
SSO Login Flows
Dotwork supports two SSO login flows. You can enable one or both depending on your organization's needs:
IdP-Initiated SSO — Users sign in from your Identity Provider (e.g. clicking a Dotwork tile in Okta or Azure AD) and are redirected into Dotwork.
SP-Initiated SSO — Users start at the Dotwork sign-in page, enter their work email, click "Sign in with SSO," and are redirected to your IdP to authenticate before being returned to Dotwork.
Setup | How users sign in | Configuration needed |
IdP-Initiated only | From IdP dashboard (app tile) | RelayState in IdP |
SP-Initiated only | From Dotwork sign-in page | Verified domain in WorkOS |
Both (recommended) | Either way | RelayState in IdP + verified domain in WorkOS |
SP-Initiated SSO
SP-initiated SSO works automatically once your SAML connection is active and your email domain is verified in WorkOS (this is typically handled during the Admin Portal setup).
Users navigate to your Dotwork site (e.g. https://YOUR-SITE.dotwork.app), enter their email, click "Sign in with SSO". Dotwork will look up your organization by email domain, redirect to your IdP for authentication, and then return the user to the same Dotwork site they started from.
Access to multiple sites (prod + test) with SP-Initiated SSO
If you have multiple Dotwork sites sharing the same email domain (for example, YOUR-SITE.dotwork.app and YOUR-TEST-SITE.dotwork.app), SP-initiated SSO handles this automatically. Users are always redirected back to whichever Dotwork site they initiated the login from — no additional configuration is needed.
IdP-Initiated SSO
RelayState (required for IdP-Initiated)
To ensure users are redirected to the correct Dotwork site after authenticating from your IdP, please set your IdP's RelayState (sometimes called Default Relay State, Target URL, or RelayState) to:
redirect_uri=https://YOUR-SITE.dotwork.app/auth/callback/saml
Access to multiple sites (prod + test) with IdP-Initiated SSO
If you have multiple sites (for example, production and a test/sandbox site), you can typically reuse the same WorkOS SAML connection and create multiple apps/tiles in your IdP — each with a different RelayState.
Example for a test site:
redirect_uri=https://YOUR-TEST-SITE.dotwork.app/auth/callback/saml
If your IdP doesn't support different RelayState values per app/tile, another option is to append RelayState to the IdP SSO URL as a URL-encoded query parameter:
<IDP_SSO_URL>?RelayState=redirect_uri%3Dhttps%3A%2F%2FYOUR-SITE.dotwork.app%2Fauth%2Fcallback%2Fsaml
Tip: If managing RelayState for multiple sites is cumbersome in your IdP, consider having users sign in via SP-Initiated SSO instead. Users simply navigate to the correct Dotwork site and click "Sign in with SSO" — no RelayState configuration required.
Need multiple IdPs or separate configurations?
If you need multiple IdP configurations (or can't vary RelayState and need truly separate setups), let us know. We can provision additional WorkOS organizations/connections as needed; additional unique configurations may incur additional costs.