WorkOS Docs Homepage
DashboardSign In

Shibboleth Generic SAML

Learn how to configure a Shibboleth Generic connection via SAML.

These instructions are for connecting to Shibboleth using the generic SAML 2.0 configuration. If the organization requires the UnsolicitedSSOConfiguration instead, please use the Shibboleth Unsolicited SAML provider documentation.

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 Shibboleth Generic SAML connection, you’ll need the Identity Provider metadata that is available from the organization’s Shibboleth instance.

Start by logging in to your WorkOS dashboard and browse to the “Organizations” tab on the left hand navigation bar.

Select the organization you wish to configure a Shibboleth Generic SAML connection for, and select “Manually Configure Connection” under “Identity Provider”.

A screenshot showing where to find "Manually Configure Connection" in the WorkOS Dashboard.

Select “Shibboleth Generic SAML” from the Identity Provider dropdown, enter a descriptive name for the connection, and then select the “Create Connection” button.

A screenshot showing "Create Connection" details in the WorkOS Dashboard.

Once you’ve created your connection, WorkOS provides the ACS URL, SP Metadata link, and SP Entity ID. It’s readily available in your connection settings in the WorkOS Dashboard.

A screenshot showing where to find the ACS URL, SP Metadata and SP Entity ID in the WorkOS Dashboard.

The ACS URL is the location an Identity Provider redirects its authentication response to. The SP Metadata link contains a metadata file that the organization can use to set up the Shibboleth Generic SAML integration.

The SP Entity ID is a URI used to identify the issuer of a SAML request and the audience of a SAML response. In this case, the SP Entity ID is used to communicate that WorkOS will be the party performing SAML requests to the organization’s Shibboleth instance, and that WorkOS is the intended audience of the SAML responses from the Shibboleth instance.

In order to integrate you’ll need the Shibboleth IdP metadata.

Normally, this information will come from the organization’s IT Management team when they set up your application’s Shibboleth configuration. 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 Shibboleth setups, you can use the metadata found at the SP Metadata link to configure the Shibboleth connection.

Download the IdP metadata from the Shibboleth instance. Refer to the Shibboleth documentation for more information on this metadata file. Keep in mind where the file was saved, as we’ll be uploading it later to configure the Connection.

At a minimum, the Attribute Statement in the SAML Response should include id, email, firstName, and lastName attributes. Refer to the Shibboleth documentation for more information on adding and mapping 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.

In the connection settings in the WorkOS Dashboard, click “Edit Metadata Configuration”.

A screenshot showing where to edit the IdP metadata URL in the WorkOS Dashboard.

Upload the XML metadata file from Shibboleth into the “Metadata File” field and select “Save Metadata Configuration”. Your connection will then be linked and good to go!

A screenshot showing where to upload and how to save the IdP metadata URL in the WorkOS Dashboard.