This example requires the following components:
  • An SP adapter instance deployed, configured, and integrated with the target application.
  • An IdP connection to the partner. For more information, seestep 1.
  • An IdP connection to the third-party IdP that facilitates the multifactor authentication process. For more information, seestep 2.
  • An authentication policy contract to carry user attributes from the partner to the target application. For more information, see step 3.
  • An SP authentication policy. For more information, see step 4 and step 7.
  • An adapter mapping between the authentication policy contract and the applicable SP adapter instance. For more information, see step 5.
  • An SP-initiated single sign-on (SSO) URL. For more information, see step 6.

In this example, you want to create an IdP connection to Alpha, which passes two attributes in its assertions, SAML_SUBJECT and samlEmail, on your PingFederate SP server. You also want to enforce multi-factor authentication (MFA) for users from Alpha through Bravo, a third-party IdP that returns only the SAML_SUBJECT attribute and requires a user ID to be passed in from the original source. Both Alpha and Bravo support SAML 2.0 and only the SP-initiated single sign-on (SSO) profile.

Create an SP adapter instance using the Applications > Integration > SP Adapters configuration wizard and complete the last-mile integration with the target application. The SP adapter instance name and ID are Sample and sample, respectively. On System > Server > Protocol Settings > Federation Info, the base URL for your PingFederate SP server is https://sso.xray.local:9031. There are no other IdP connections besides those required to connect with Alpha and Bravo.

  1. Go to Authentication > Integration > IdP Connections. On the IdP Connections window, click Create Connection.
    1. Follow the connection workflow to create a SAML 2.0 IdP connection to Alpha.

      In this example, Alpha's entity ID is sso.alpha.local.

    2. On the SAML Profiles tab, make sure that the SP-Initiated SSO check box is selected.
    3. On the Identity Mapping window, select No Mapping.
      Tip:

      If the partner and your organization agree to support account linking, select Account Linking. If the partner and your organization agree to support the IdP-initiated profile, select Account Mapping or Account Linking.

      Both use cases require the applicable SP adapter instance (Sample) to be mapped into the connection. To get to the Target Session Mapping tab, go to IdP Connection > Browser SSO > User-Session Creation. The rest of the steps remain unchanged.

      This sample configuration uses neither Account Linking or Account Mapping.

    4. Complete the rest of the connection configuration.
  2. Repeat step 1 to create a SAML 2.0 IdP connection to Bravo.

    In this example, Bravo's entity ID is sso.bravo.local.

  3. Go to Authentication > Policies > Policy Contracts. On the Policy Contracts window, click Create New Contract.
    Tip:

    The purpose of an authentication policy contract is to harness user attributes obtained through one or more authentication sources as the request flows through the applicable authentication policy. It is the medium between the authentication policies and the target applications. In general:

    • You map attributes to authentication policy contracts from authentication policies. For more information, see step 4 in this example.
    • You map attributes from authentication policy contracts to target applications through adapter mappings. For more information, see step 5 in this example.
    1. On the Contract Info tab, enter a name for this authentication policy contract.

      In this example, the name of the policy contract is Authenticated.

    2. On the Contract Attributes tab, enter mail under Extend the Contract and click Add.
    3. Complete the rest of the connection configuration.

    When finished, your policy contract has two attributes: subject and mail.

  4. Go to Authentication > Policies > Policies. On the Policies window, click Add Policy to define a policy to enforce the third-party authentication requirement.
    1. On the Policy window, enter a name and a description for this policy, and select sso.alpha.local (IdP Connection) as the first policy action from the list.

      An IdP connection has two results, Fail and Success, as illustrated in the following screen capture.

      Screen capture illustrating the Fail and Success IdP connection results.

      Each result forms its own policy path that requires further configuration.

    2. For the sso.alpha.local > Fail path, click Done as the policy action.

      At runtime, PingFederate terminates the request and returns an error message to the user.

    3. From the sso.alpha.local > Success list, select sso.bravo.local as the policy action.
    4. Below sso.bravo.local, click Options to relay the user ID (SAML_SUBJECT) from sso.alpha.local to sso.bravo.local.
    5. On the Incoming User ID dialog window, select IdP Connection (sso.alpha.local) from the Source list and SAML_SUBJECT from the Attribute list.
      Screen capture illustrating the Incoming user ID dialog window.

      To close the Incoming User ID dialog window, click Done.

    6. For the sso.bravo.local > Fail path, select Done as the policy action.

      At runtime, PingFederate terminates the request and returns an error message to the user.

    7. For the sso.bravo.local > Success path, select the authentication policy contract created in step 3.

      Your policy should be similar to the following sample.

      Screen capture illustrating a configured Success path for an IdP policy contract.
    8. Below the authentication policy contract, click Contract Mapping and follow the Manage Authentication Policies > Authentication Policy Contract Mapping configuration workflow to configure the fulfillment of the authentication policy contract.
    9. On the Attribute Sources & User Lookup tab, click Add Attribute Source to configure datastore queries.
    10. On the Contract Fulfillment tab, from the Source list select IdP Connection (sso.alpha.local) and the appropriate attributes from the Value list to fulfill the authentication policy contract attributes.
      Screen capture illustrating a configured authentication policy contract fulfillment.
      Tip:

      In this configuration, you are mapping attributes to an authentication policy contract from the authentication policy.

      Optional: On the Issuance Criteria tab, configure conditions to be validated before issuing an authentication policy contract.

      On the Summary tab, click Done.

      On the Policy window, click Done.

      On the Policies window, click Save.

  5. Go to Applications > Integration > Policy Contract Adapter Mappings. Map the authentication policy contract to the SP adapter instance that you have deployed, configured, and integrated with the target application.
    1. From the Source Instancelist, select the authentication policy contract, created in step 3.
    2. From the Target Instance list, select the applicable SP adapter instance (Sample).
    3. Click Add Mapping.
    4. Follow the Mapping Configuration workflow to create the mapping.
    5. On the Attribute Sources & User Lookup tab, click Add Attribute Source to configure datastore queries.
    6. On the Adapter Contract Fulfillment window, select Authentication Policy Contract from the Source list and the appropriate contract attributes from the Value list to fulfill the SP adapter contract.
      Screen capture illustrating a configured adapter contract fulfillment tab.
      Tip:

      In this configuration, you are mapping attribute values from the authentication policy contract to the target application through the applicable SP adapter instance.

      Optional: On the Default Target URL tab, specify a default target URL for this mapping configuration.

      Optional: On the Issuance Criteria tab, configure conditions to be validated before issuing an SP adapter contract.

      Click Done.

  6. Configure an SP-initiated SSO URL in your target application by combining the base URL of your PingFederate SP server, https://sso.xray.local:9031, the PingFederate's application SSO endpoint, /sp/startSSO.ping, and the SpSessionAuthnAdapterId parameter with the adapter ID of the applicable SP adapter instance as the parameter value.

    For example: https://sso.xray.local:9031/sp/startSSO.ping?SpSessionAuthnAdapterId=sample

    If you have not defined a default URL for the adapter mapping, configured in step 5, the IdP connection, or the PingFederate SP server, you must also configure your target application to include the TargetResource parameter in its SP-initiated SSO requests.

    Important:

    When using the parameters TargetResource or TARGET with their own query parameters included, the parameter value must be URL-encoded. Any other parameters that contain restricted characters, such as many SAML URNs, also must be URL-encoded. For information about URL encoding, see third party resources such as HTML URL-encoding Reference. Parameters are case-sensitive.

  7. When you are ready to test your new use case, go to Authentication > Policies > Policies. On the Policies window, select the SP Authentication Policies check box to enable policies for SP-initiated Browser SSO requests received by at the /sp/startSSO.ping endpoint, and click Save.