Shibboleth Generic 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”.

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

Once you’ve created your connection, WorkOS provides the ACS URL, SP Metadata link, and IdP URI (Entity ID). It’s readily available in your connection settings 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 Entity ID is a URI used to identify the issuer of a SAML request, response, or assertion. In this case, the entity ID is used to communicate that WorkOS will be the party performing SAML requests to the organization's 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 “IdP URI (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 minumum, 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.

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”.

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!