Single Sign-On

Connect SAML

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.

Currently Supported Provider Connections:

Creating a SAML connection in the WorkOS Dashboard

Step 1: Navigate to the Connections Tab

Click "Single Sign-on" in the left-hand sidebar, and navigate to "Connections". Then, click the "New Connection" button.

Step 2: Provide your Enterprise Client's Details

Enter the name of your client in the "Company name" field, as well as their domain in the "Domain URL" field.

Step 3: Select Identity Provider

Then, select your client's identity provider.

Step 4: Click "Create connection"

Step 5: Configure the new connection

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.

Step 6: Click "Update Connection"

Your Connection should be "Verified" and ready to authenticate users.

Using the SSO Attribute Mapper

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 firstName, lastName, email, and 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 Profile.

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.