Learn how to configure a connection to PingFederate via SAML
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 PingFederate SAML Connection, you'll need four pieces of information: an ACS URL, an Identity Provider Issuer (also known as an Entity ID), an Identity Provider SSO URL, and an X.509 Certificate.
WorkOS provides the ACS URL. It's readily available in your Connection's Settings in the Developer Dashboard.
The ACS URL is the location an Identity Provider redirects its authentication response to. In PingFederate's case, the ACS URL needs to be set by the Enterprise when configuring your application in their PingFederate instance.
Specifically, the ACS URL needs to be set as the "Endpoint URL" when defining the Protocol Settings in the SP Connection for WorkOS.
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 assertions via the Enterprise's PingFederate instance.
Specifically, the Entity ID needs to be set as the "Partner's Entity ID (Connection ID)" when defining the General Info Settings in the SP Connection for WorkOS.
Configuring Ping Federate SAML
And then you provide the PingFederate SSO URL and X.509 certificate.
Normally, this information will come from your Enterprise customer's IT Management team when they set up your application's SAML 2.0 configuration in their PingFederate admin dashboard. However, that should not be the case during your setup. Here's how to obtain them:
1Log in and Select your Application
Log in to the PingFederate admin dashboard, select "Applications" at the top, select the "SP Connections" menu option.
2Obtain Identify Provider Details
On the SP Connection list, find your WorkOS SAML 2.0 connection. Click on the "Select Action" menu and then select "Export Metadata" to download the connection metadata.
In the metadata file, you'll see the following line:
SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://mypingfederate.com/idp/SSO.saml2" Copy and paste the Location URL into the IdP SSO URL field in your WorkOS Developer Dashboard.
To download the X.509 certificate, navigate to the "Security" top menu and go to "Signing & Decryption Keys & Certificates". Select the X.509 certificate used to sign the SAML Response in the WorkOS SP Connection. Click the "Select Action" menu and select "Export". Save this file.
3Configure Attribute Mapping
In the SP Connection setup for the WorkOS SAML 2.0 connection, you need to add id, email, firstName, and lastName attributes in the "Browser SSO" menu during the "Assertion Creation" section for the "Attribute Contract".
How you map values to the attributes listed above may differ based on how your PingFederate instance is set up. Below is an example of mapping values from both an Authentication Policy Contract and an LDAP directory.
Finally, upload the X.509 Certificate in your WorkOS Connection Settings. Your Connection will then be linked and good to go!