You can configure an SP authentication policy to enforce authentication requirements for an IdP connection. Consider the following example.

You are tasked to create an IdP connection to Alpha, which passes two attributes in its assertions, SAML_SUBJECT and samlEmail, on your PingFederate SP server. You are also asked to enforce multifactor authentication 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 SSO profile.

You have already created an SP adapter instance using the Service Provider > Adapters configuration wizard and completed the last-mile integration with the target application. The SP adapter instance name and ID are Sample and sample, respectively. On the System > Protocol Settings > Federation Info screen, the base URL for your PingFederate SP server is defined as https://sso.xray.local:9031. There are no other IdP connections besides those required to connect with Alpha and Bravo.

This example requires the following components:

  • An SP adapter instance deployed, configured, and integrated with the target application.
  • An IdP connection to the partner (step 1).
  • An IdP connection to the third-party IdP that facilitates the multifactor authentication process (step 2).
  • An authentication policy contract to carry user attributes from the partner to the target application (step 3).
  • An SP authentication policy (step 4 and step 7).
  • An adapter mapping between the authentication policy contract and the applicable SP adapter instance (step 5).
  • An SP-initiated SSO URL (step 6).

To fulfill the requirements:

  1. On the Service Provider menu, click Create New (under IdP Connections).
    1. Follow the connection wizard to create a SAML 2.0 IdP connection to Alpha.

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

    2. On the IdP Connection > Browser SSO > SAML Profiles screen, make sure that the SP-Initiated SSO check box is selected.
    3. On the IdP Connection > Browser SSO > User-Session Creation > Identity Mapping screen, 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 in the IdP Connection > Browser SSO > User-Session Creation > Target Session Mapping screen. The rest of the steps remain unchanged.

      (This sample configuration uses neither Account Linking nor 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. On the Service Provider > Policy Contracts screen, 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. Generally speaking:

    • You map attributes to authentication policy contracts from authentication policies (step 4 in this example).
    • You map attributes from authentication policy contracts to target applications through adapter mappings (step 5 in this example).
    1. On the Contract Info screen, enter a name for this authentication policy contract.
      In this example, the name of the policy contract is Authenticated.
    2. On the Contract Attributes screen, 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. On the Service Provider > Policies screen, click Add Policy to define a policy to enforce the third-party authentication requirement.
    1. On the Policy screen, 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:

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

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

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

    3. For the sso.alpha.local > Success path, select sso.bravo.local as the policy action.
    4. Click Options (underneath sso.bravo.local) to relay the user ID (SAML_SUBJECT) from sso.alpha.local to sso.bravo.local.
      On the Incoming User ID dialog, select IdP Connection (sso.alpha.local) from the Source list and SAML_SUBJECT from the Attribute list; for example:
      Incoming user ID

      Click Done to close the Incoming User ID dialog.

    5. 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.

    6. 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:

    7. Click Contract Mapping (underneath the authentication policy contract) and follow the Manage Authentication Policies > Authentication Policy Contract Mapping configuration wizard to configure the fulfillment of the authentication policy contract.
      Optional: On the Attribute Sources & User Lookup screen, click Add Attribute Source to configure datastore queries.

      On the Contract Fulfillment screen, select IdP Connection (sso.alpha.local) from the Source list and the appropriate attributes from the Value list to fulfill the authentication policy contract attributes; for example:

      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 screen, configure conditions to be validated before issuing an authentication policy contract.

      On the Summary screen, click Done.

      On the Policy screen, click Done.

      On the Authentication Policies screen, click Save.

  5. On the Service Provider > Adapter Mappings screen, map the authentication policy contract to the SP adapter instance that you have deployed, configured, and integrated with the target application.
    1. Select the authentication policy contract (created in step 3) from the Source Instance list.
    2. Select the applicable SP adapter instance (Sample) from the Target Instance list.
    3. Click Add Mapping.
    4. Follow the Authentication Policy Adapter Mappings > Mapping Configuration wizard to create the mapping.
      Optional: On the Attribute Sources & User Lookup screen, click Add Attribute Source to configure datastore queries.

      On the Adapter Contract Fulfillment screen, select Authentication Policy Contract from the Source list and the appropriate contract attributes from the Value list to fulfill the SP adapter contract; for example:

      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 screen, specify a default target URL for this mapping configuration.

      Optional: On the Issuance Criteria screen, 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 the parameter TargetResource (or TARGET) is used and includes its own query parameters, the parameter value must be URL-encoded.

    Any other parameters that contain restricted characters (many SAML URNs, for example) also must be URL-encoded.

    For information about URL encoding, please refer to third party resources, such as HTML URL-encoding Reference (www.w3schools.com/tags/ref_urlencode.asp).

  7. When you are ready to test your new use case, go to the Service Provider > Policies screen, 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.