WorkOS Docs Homepage
DashboardSign In

PingFederate SAML

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 the Identity Provider metadata that is available from your PingFederate instance.

WorkOS provides the ACS URL 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 and SP Entity ID in the WorkOS 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 organization 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.

A screenshot showing where the ACS URL needs to be set in the PingFederate settings.

The SP 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 organization’s PingFederate instance.

Specifically, the SP 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.

A screenshot showing where to set the SP Entity ID in the PingFederate settings.

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

Normally, this information will come from the organization’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:

Log in to your PingFederate instance, go to the admin dashboard, select “Applications” at the top, and select the “SP Connections” menu option.

A screenshot showing where to find the SP Connections section in the PingFederate admin dashboard.

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 IdP metadata.

A screenshot showing where to download the IdP metadata file in PingFederate.

Keep in mind where the file was saved, as we’ll be later uploading it to configure the Connection.

In the SP Connections dashboard, click into your desired connection. From there, click into the “Activation & Summary” tab, then click “Attribute Contract”. You will need to add id, email, firstName, and lastName as attributes. Once configured, click “Next”.

A screenshot showing where to configure attribute mapping in PingFederate.

You will now need to configure an Authentication Policy Contract. To do so, click “Map New Authentication Policy”, then click “Manage Policy Contracts” and “Create New Contract”. Name your contract, then go to the next step and add the same four attributes we configured above. Continue through the steps, then click “Save”.

A screenshot showing where to extend the Authentication Policy Contract in PingFederate.

On the “Authentication Policy Mapping” page, select the Authentication Policy Contract you just made and click “Next”. In the “Attribute Contract Fulfillment” tab, 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 mapped values from both an Authentication Policy Contract and an LDAP directory. From there, save your settings on the “Summary” tab to lock in the configuration.

A screenshot showing an example of Authentication Policy Mappings in PingFederate.

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.

Navigate back to the “Attribute Contact” page and define a groups attribute.

A screenshot showing where to define a groups attribute in PingFederate.

Then, navigate to the “Attribute Contract Fulfillment” page and map the new groups attribute to the data in your provider that includes group memberships, such as the isMemberOf LDAP attribute in the example below.

A screenshot showing a mapped groups attribute in the Attribute Contract Fulfillment area in PingFederate.

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

A screenshot showing where to edit the Metadata Configuration in the WorkOS Dashboard.

In the modal, upload the PingFederate Metadata file and then select “Save Metadata Configuration”. Once the file is uploaded into WorkOS, your connection will then be linked and good to go!

A screenshot showing where to upload the Metadata file in the WorkOS Dashboard.