SAML

To set up a SAML connection on behalf of an organization, you’ll need the identity provider metadata or manual configuration details from the organization’s IT team.

When setting up a SAML connection, WorkOS provides three key pieces of information in the Service Provider Details section for an SSO connection within the WorkOS Dashboard:

• SP Entity ID: A unique identifier that represents your application in SAML communications
• ACS URL: The endpoint where identity providers send authentication responses
• SP Metadata: A configuration file containing all necessary SAML settings

These settings are required to configure a SAML integration. The ACS URL serves as the destination for authentication responses, while the SP Entity ID uniquely identifies your application in SAML requests and responses. The SP Metadata URL provides a complete configuration file that simplifies the setup process for the organization.

You will need to obtain one of the following from the organization:

• Identity Provider Metadata URL: Configuration URL containing SAML metadata (preferred)
• Manual configuration details: SSO URL, Entity ID, and X.509 Certificate (if metadata URL is not available)

Typically, the organization’s IT team will provide these values when they configure your application in their identity provider admin dashboard. However, if you need to guide them through the process, the following sections will help.

For SSO to properly function, the organization needs to create and configure a SAML application in their identity provider.

Copy the ACS URL and SP Entity ID from the Service Provider Details section in the WorkOS Dashboard.

Instruct the organization admin to paste these values into the corresponding fields in their identity provider’s admin dashboard. Alternatively, they can use the service provider metadata URL to automatically configure the SAML connection if their identity provider supports metadata-based configuration.

After the organization creates a SAML application, their identity provider will provide either a metadata URL or manual configuration details.

If they have a metadata URL, in the WorkOS Dashboard, navigate to the Identity Provider Configuration section. Click Edit Configuration.

Paste the metadata URL from the organization’s IT team into the input field. Your connection will be automatically configured once the metadata is processed.

If the organization’s identity provider doesn’t provide a metadata URL, you’ll need to manually configure the connection by clicking the Switch to Manual Configuration option and entering the SSO URL, Entity ID, and X.509 Certificate provided by their IT team.

The organization’s SAML provider needs to include specific attributes in the SAML response. Instruct them to configure their SAML application to include the following attributes in the Attribute Statement:

• id: Maps to the idp_id attribute in WorkOS user profiles
• email: Maps to the email attribute in WorkOS user profiles
• firstName: Maps to the first_name attribute in WorkOS user profiles
• lastName: Maps to the last_name attribute in WorkOS user profiles

With identity provider role assignment, users can receive roles within your application based on their group memberships. To enable this functionality, instruct the organization to add a groups attribute to the SAML response that maps to a list of the user’s group memberships.