WorkOS Docs Homepage
DashboardSign In


Learn how to configure a new custom SAML connection.

Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.

To create a custom SAML Connection, you’ll need the Identity Provider Metadata URL that is available from the organization’s SAML instance.

WorkOS provides the ACS URL, the SP Entity ID, and the SP Metadata link. They are readily available in your Connection Settings in the WorkOS Dashboard.

WorkOS Settings

The ACS URL is the location an Identity Provider redirects its authentication response to. The SP Entity ID is a URI used to identify the issuer of a SAML request and the audience of a SAML response. The SP Metadata link contains a metadata file that the organization can use to set up the SAML integration.

In order to integrate you’ll need the IdP Metadata URL.

Normally, this information will come from the organization’s IT Management team when they set up your application’s SAML 2.0 configuration in their Identity Provider admin dashboard. But, should that not be the case during your setup, here’s how to obtain them.

Copy and Paste the “ACS URL” and “SP Entity ID” into the corresponding fields for Service Provider details and configuration. For some SAML setups, you can use the metadata found at the SP Metadata link to configure the SAML connection.

Copy the IdP Metadata URL from your SAML settings and upload it to your WorkOS Connection settings. Your Connection will then be linked and good to go!

Upload IdP Metadata URL to WorkOS Dashboard

Some SAML providers might not be able to provide the IdP Metadata URL. In these cases, you’ll want to manually configure the connection.

Switch to Manual Configuration
Manually Configure Connection in WorkOS Dashboard

At a minimum, the Attribute Statement in the SAML Response should include id, email, firstName, and lastName attributes.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named groups.