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”.
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 SP 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 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.
With identity provider role assignment, users can receive roles within your application based on their group memberships. To return this information in the attribute statement, map the groups in your identity provider to a SAML attribute named groups.
Once your SAML app is configured to return groups, navigate to the Connection page in the Organization section of the WorkOS Dashboard. Create connection groups referencing the group IdP ID. Then, assign roles to connection groups so users in those groups will automatically be granted roles within your application.
