Learn how to create and configure new SSO connections using the WorkOS Developer Dashboard
This guide walks through setup of a SAML Connection using the WorkOS Developer Dashboard. Your Enterprise clients may have configured their Identity Provider with SAML, AD FS, or OAuth. You'll need to know their Identity Provider before proceeding.
Click "Single Sign-on" in the left-hand sidebar, and navigate to "Connections". Then, click the "New Connection" button.
Enter the name of your client in the "Company name" field, as well as their domain in the "Domain URL" field.
Then, select your client's identity provider.
You'll then be provided with your new Connection's configuration options.
Each Enterprise Client's connection requires the following information:
ACS URL— This is an endpoint where an Identity Provider posts SAML responses. (WorkOS will handle this for you.)
Identity Provider Issuer (Entity ID)— This is a globally unique name for an Identity Provider or a Service Provider that performs SAML authentication assertions.
Identity Provider SSO URL— This is the URL your application's users with be redirected to for authentication with an Identity Provider.
X.509 Certificate— This is a public key certificate used to authenticate SAML assertions.
Your Connection should be "Verified" and ready to authenticate users.
Attribute mappings are used to match user attributes that WorkOS provides your application, with like attributes from your Enterprise customer's identity provider. With attribute mappings, WorkOS is able to provide you with a user
Profile object that always contains the
id attributes, no matter how your Enterprise customer maps their user attributes.
An attribute mapping is generated for each SSO Connection, using your Enterprise customer's identity provider attribute map:
When any of your Enterprise users attempt to authenticate and any of the available attributes are not recognized by your Connection's Attribute Map, you will receive an email notification that an invalid
Profile was created.
Your Enterprise user will be redirected to a page notifying them that this Connection requires additional configuration, and that you have been contacted to make the necessary changes.
In your email notification, you'll receive a link to the Connection that requires attribute mapping. This Connection's page will list the raw attributes from the most recent unsaved
Profile object. Then, you'll be able to update the default, existing attribute map to match the raw attributes provided by the unsaved
Once the attribute mapping has been updated, the previously invalid
Profile will attempt to re-map, and validation will confirm whether or not the re-map was successful. The page will then display a list of Enterprise profiles that have failed to authenticate, as well as suggested email messages asking them to sign in again.
The available configuration information can vary slightly by Identity Provider. Check out the specific guide for each Identity Provider to learn what information is required:
Another option for configuring connections is WorkOS.js. This allows you to embed the configuration flow directly within your application, enabling enterprise admin users to set up SSO without leaving your app. (The flow is similar to Stripe Checkout or Plaid Link.)
To learn more, visit the docs for WorkOS.js.