WorkOS Docs Homepage

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 your Enterprise customer 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 your Enterprise customer’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 your Enterprise customer 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 to that WorkOS will be the party performing SAML requests to the Enterprise’s Shibboleth instance.

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

Normally, this information will come from your Enterprise customer’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 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.

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!