Assume you configure the following use cases in an earlier version of PingFederate:

  • Two SP adapter instances onApplications > Integration > SP Adapters.
    Instance Name Instance ID Extended Contract
    Sample sample subject and email
    Sample Delta sampleDelta subject and email
  • Three entries on Applications > Integration > Target URL Mapping.
    URL Target Session
    https://sso.xray.local:9031/SpSample/MainPage?app=Alpha&* Sample
    https://sso.xray.local:9031/SpSample/MainPage?app=Charlie&* Sample
    https://sso.xray.local:9031/SpSample/MainPage?app=Delta&* Sample Delta
  • Three IdP connections to your partners.
    Partner

    (Federation ID)

    		 Identity Mapping Attribute Contract Target Session Mapping

    SP adapter instance name

    (SP adapter instance ID)
    Alpha

    (sso.alpha.local)

    		 Account Mapping SAML_SUBJECT and samlEmail Sample

    (sample)
    Charlie

    (sso.charlie.local)

    		 Account Mapping SAML_SUBJECT and samlEmail Sample

    (sample)
    Delta

    (sso.delta.local)

    		 Account Mapping SAML_SUBJECT and samlEmail Sample Delta

    (sampleDelta)

    In this example, all partners support SAML 2.0 and only the SP-initiated single sign-on (SSO) profile.

  • SP-initiated SSO URLs for users from Alpha, Charlie, and Delta.
    Partner SSO URL
    Alpha https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.alpha.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DAlph%26t%3Daa
    Charlie https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.charlie.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DCharlie%26t%3Dc
    Delta https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.delta.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DDelta%26t%3Dd
After upgrading to PingFederate 10.1, you have the following new requirements:
  • Create new IdP connections to three new partners: Echo, Foxtrot and Golf.
  • Enforce multi-factor authentication (MFA) for users from Alpha, Charlie, Echo, and Golf through Bravo.

    Bravo requires a user ID to be passed in from the original source and returns only the user ID when the users fulfill the multi-factor authentication (MFA) requirement.

The new required components are:

  • Two additional SP adapter instances. For more information, seestep 1:
    • Sample Echo to integrate with Echo's target application.
    • Sample Golf to integrate with Golf's target application.
  • Four new IdP connections. For more information, see step 2, step 3, and step 4:
    Partner

    (Federation ID)

    		 Identity Mapping Attribute Contract Target Session Mapping

    SP adapter instance name

    (SP adapter instance ID)
    Bravo

    (sso.bravo.local)

    		 No Mapping SAML_SUBJECT and no other attributes N/A
    Echo

    (sso.echo.local)

    		 No Mapping SAML_SUBJECT and samlEmail N/A
    Foxtrot

    (sso.foxtrot.local)

    		 Account Mapping SAML_SUBJECT and samlEmail Sample

    (sample)
    Golf

    (sso.golf.local)

    		 No Mapping SAML_SUBJECT and samlEmail N/A

    In this example, all partners support SAML 2.0 and only the SP-initiated SSO profile.

  • Three authentication policy contracts. For more information, see step 5:
    • An authentication policy contract, Authenticated, to carry user attributes from Alpha and Charlie to their respective target applications.
    • Two other authentication policy contracts, Echo authenticated and Golf authenticated, to carry user attributes from Echo and Golf to their target applications.
  • An instance of the HTTP Request Parameter Authentication Selector, PartnerIdpId, to determine if a request is meant for Alpha or Charlie, because Alpha's and Charlie's target applications share an SP adapter instance. For more information, see step 6.
  • Three SP authentication policies to enforce the multifactor authentication requirement. For more information, see step 7, step 8, and step 12.
  • Three adapter mappings between the authentication policy contracts and the applicable SP adapter instances. For more information, see step 9:
    • Map from Authenticated to Sample.
    • Map from Echo authenticated to Sample Echo.
    • Map from Golf authenticated to Sample Golf
  • Three additional target URL mappings between the applications requested by users from Echo, Foxtrot, and Golf to their respective SP adapter instances. For more information, see step 10:
  • SSO URLs for all partners. For more information, see step 11.

Follow these steps to fulfill the new requirements:

  1. Go to Applications > Integration > SP Adapters. On the SP Adapters window, create two new SP adapter instances, as shown in the following table.
    Instance Name Instance ID Extended Contract
    Sample Echo sampleEcho subject and email
    Sample Golf sampleGolf subject and email
  2. Create an IdP connection to Bravo.
    1. On the IdP Connections window (Authentication > Integration > IdP Connections) create a SAML 2.0 IdP connection.
    2. On IdP Connection > Browser SSO > SAML Profiles, select the SP-Initiated SSO check box.
    3. On IdP Connection > Browser SSO > User-Session Creation > Identity Mapping, select No Mapping.
    4. Complete the rest of the connection configuration.
  3. Create IdP connections to Echo and Golf.
    1. Go to Authentication > Integration > IdP Connections. On the IdP Connections window, create a SAML 2.0 IdP connection to Echo, and then to Golf.
    2. On IdP Connection > Browser SSO > SAML Profiles, select the SP-Initiated SSO check box.
    3. On IdP Connection > Browser SSO > User-Session Creation > Identity Mapping, select No Mapping.
      Tip:

      If the partner and your organization agree to support account linking, select Account Linking. When the Account Linking option is selected, you must map the applicable SP adapter instance, Sample Echo for Echo or Sample Golf for Golf, to the connection on IdP Connection > Browser SSO > User-Session Creation > Target Session Mapping. The rest of the steps remain unchanged.

      This example does not use account linking.

    4. On IdP Connection > Browser SSO > User-Session Creation > Attribute Contract, enter samlEmail under Extend the Contract.
    5. Complete the rest of the connection configuration.
    6. Repeat these steps to create a SAML 2.0 IdP connection to Golf.
  4. Create an IdP connection to Foxtrot.
    1. On the IdP Connections window, create a SAML 2.0 IdP connection.
    2. On IdP Connection > Browser SSO > SAML Profiles, select the SP-Initiated SSO check box.
    3. On the User-Session Creation tab, click Configure User-Session Creation.
    4. On the Identity Mapping tab, select Account Mapping.
    5. On the Attribute Contract tab, enter samlEmail under Extend the Contract.
    6. On the Target Session Mapping tab, click Map New Adapter Instance and follow the Adapter Mapping & User Lookup configuration workflow to map the attributes from the assertion to the SP adapter instance Sample.
      Adapter Contract Source Value
      email Assertion samlEmail
      subject Assertion SAML_SUBJECT
    7. Complete the rest of the connection configuration.
  5. Create three authentication policy contracts, one for Alpha and Charlie, one for Echo, and one for Golf.
    Note:

    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, seestep 7 in this example.
    • You map attributes from authentication policy contracts to target applications through adapter mappings. For more information, see step 9 in this example.
    1. Go to Authentication > Policies > Policy Contracts. On the Policy Contracts window, click Create New Contract to create an authentication contract for users from Alpha and Charlie, for users from Echo, and then for users from Golf.
    2. On the Contract Info tab, enter a name for this authentication policy contract.

      In this example, the names are Authenticated, Echo authenticated, and Golf authenticated.

    3. On the Contract Attributes tab, extend the authentication policy contract with an attribute for user's email address, such as mail.
    4. Complete the rest of the connection configuration.
    5. Repeat these steps to create an authentication policy contract for users from Echo, and then for users from Golf.

      Your policy contracts should be similar to the following samples.

      Screen capture illustrating completed authentication policy contracts for Echo and Golf.
  6. Note:

    If multiple target applications share the same SP adapter instance, you must use a selector to evaluate the SP-initiated requests such that the policy engine can route the requests to the policy paths that are meant for the respective IdPs. This example uses an instance of the HTTP Request Parameter Authentication Selector to categorize requests based on their respective PartnerIdpId query parameter values at runtime. The policy diverts accordingly based on the selector results.

    Create an instance of the HTTP Request Parameter Authentication Selector.
    1. Go to Authentication > Policies > Selectors. On the Selectors window, click Create New Instance.
    2. On the Type tab, select HTTP Request Parameter Authentication Selector from the Type list and provide a name and ID for the selector instance.

      In this example, the name and ID are both PartnerIdpId.

    3. On the Authentication Selector tab, enter PartnerIdpId in the HTTP Request Parameter Name field.
    4. On the Selector Result Values tab, enter sso.alpha.local and sso.charlie.local as the result values.
      Note:

      In general, for the IdPs that you want to enforce additional authentication requirements through one or more SP authentication policies and whose target applications share an SP adapter instance, you must enter their federation IDs here.

    5. Complete the rest of the configuration.

      Your selector instance should be similar to the following sample.

      Screen capture illustrating a completed HTTP Request Parameter Authentication Selector.
  7. Go to Authentication > Policies > Policies. On the Policies window, click Add Policy to define a policy to enforce the third-party authentication requirement for users from Echo, and then for users from Golf.
    Tip:

    If you need more information about each sub step, see step 4 in Configuring an SP authentication policy for users from one IdP.

    1. On the Policy window, enter a name and a description for this policy, and select sso.echo.local (IdP Connection) as the first policy action from the list.
    2. For the sso.echo.local > Fail path, select Done as the policy action.
    3. For the sso.echo.local > Success path, select sso.bravo.local (IdP Connection) as the policy action.
    4. Click Options, underneath sso.bravo.local (IdP Connection), to relay the user ID (SAML_SUBJECT) from sso.echo.local to sso.bravo.local.
    5. For the sso.bravo.local > Fail path, select Done as the policy action.
    6. For the sso.bravo.local > Success path, select the policy contract Echo authenticated as the policy action, and then click Contract Mapping, underneath the policy contract, to configure the fulfillment of the policy contract.
      Tip:

      Essentially, you are mapping attributes to an authentication policy contract from the authentication policy.

    7. Repeat these steps to define a new authentication policy to enforce third-party authentication for users from Golf.

      Your policies should be similar to the following samples.

      Screen capture illustrating configured default authentication sources for Echo and Golf users.
  8. On the Policies tab, click Add Policy to define a new authentication policy to enforce third-party authentication for users from Alpha and Charlie.
    Note:

    If multiple target applications share the same SP adapter instance, you must use a selector to evaluate the SP-initiated Browser SSO requests, such that the policy engine can route the requests to the policy paths that are meant for the respective IdPs. This example uses an instance of the HTTP Request Parameter Authentication Selector created in step 6.

    1. On the Policy window, enter a name and a description for this policy, and select the instance of the HTTP Request Parameter Authentication Selector as the first policy action from the list.
    2. For the sso.alpha.local path, repeat step 7 to configure the authentication requirement for the sso.alpha.local IdP connection.
    3. For the sso.charlie.local path, repeat step 7 to configure the authentication requirement for the sso.charlie.local IdP connection.
    4. For the sso.foxtrot.local path, repeat step 7 to configure the authentication requirement for the sso.foxtrot.local IdP connection.

      Your policy should be similar to the following sample.

      Screen capture illustrating configured third-party authentication for users from Alpha, Charlie, and Foxtrot.
      Note:

      This window capture collapses the sso.charlie.local and sso.foxtrot.local policy paths for documentation presentation purposes.

      When you go back to the Policies tab, your policies should be similar to the following samples.

      Screen capture illustrating the Default Authentication Sources tab configured with Alpha, Charlie, and Foxtrot users.
    5. Click Save.
  9. Create adapter mappings.
    1. Go to Applications > Integration > Policy Contract Adapter Mappings. On the Policy Contracts window, create three adapter mappings to map from the authentication policy contracts, created in step 5, to the applicable SP adapter instances.
      • Map from Authenticated to Sample.
      • Map from Echo authenticated to Sample Echo.
      • Map from Golf authenticated to Sample Golf.
      Tip:

      If you need more information about each sub step, see step 5 in Configuring an SP authentication policy for users from one IdP.

      Your mappings should be similar to the following samples.
      Screen capture illustrating configured adapter mappings for Sample, Sample Echo, and Sample Golf.

      Each adapter mapping should be similar to the following configuration.

      Screen capture illustrating authentication policy adapter mapping configuration.
      Tip:

      You are essentially mapping attribute values from the authentication policy contracts to target applications through the applicable SP adapter instances.

  10. Create target URL mappings.
    1. Go to Applications > Integration > Target URL Mapping. On the Target URL Mapping window, add the following mappings.
      URL Target Session
      https://sso.xray.local:9031/SpSample/MainPage/?app=Echo&* Sample Echo
      https://sso.xray.local:9031/SpSample/MainPage/?app=Foxtrot&* Sample
      https://sso.xray.local:9031/SpSample/MainPage/?app=Golf&* Sample Golf

      Your target URL mappings should be similar to the following samples.

      Screen capture illustrating completed target URL mapping.
  11. Configure the following SSO URLs.
    Partner SSO URL
    Alpha https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.alpha.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DAlpha%26t%3Da

    The SSO URL has not changed.

    Based on the current configuration, because the target applications for Alpha and Charlie share the same SP adapter instance, the PartnerIdpId query parameter is required for the configured policy to route the request to the corresponding IdP connection.
    Charlie https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.charlie.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DCharlie%26t%3Dc

    The SSO URL has not changed.

    Based on the current configuration, because the target applications for Alpha and Charlie share the same SP adapter instance, the PartnerIdpId query parameter is required for the configured policy to route the request to the corresponding IdP connection.
    Delta https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.delta.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DDelta%26t%3Dd

    The SSO URL has not changed.

    Optionally, based on the current configuration, you can remove the PartnerIdpId query parameter because it is not required. You can also replace the TargetResource query parameter and its value with the SpSessionAuthnAdapterId query parameter and the applicable SP adapter instance ID, SpSessionAuthnAdapterId=sampleDelta, if you have configured a default target URL in the IdP connection to Delta, or a default SP SSO URL for all IdP connections.
    Echo https://sso.xray.local:9031/sp/startSSO.ping?SpSessionAuthnAdapterId=sampleEcho&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DEcho%26t%3De

    This is a new SSO URL.

    Optionally, based on the current configuration, you can remove the TargetResource query parameter and its value if you have configured a default target URL in the IdP connection to Echo, or a default SP SSO URL for all IdP connections.
    Foxtrot https://sso.xray.local:9031/sp/startSSO.ping?PartnerIdpId=sso.foxtrot.local&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DFoxtrot%26t%3Df

    This is a new SSO URL.

    Optionally, based on the current configuration, you can remove the TargetResource query parameter and its value if you have configured a default target URL in the IdP connection to Foxtrot, or a default SP SSO URL for all IdP connections.
    Golf https://sso.xray.local:9031/sp/startSSO.ping?SpSessionAuthnAdapterId=sampleGolf&TargetResource=https%3A%2F%2Fsso.xray.local%3A9031%2FSpSample%2FMainPage%3Fapp%3DGolf%26t%3Dg

    This is a new SSO URL.

    Optionally, based on the current configuration, you can remove the TargetResource query parameter and its value if you have configured a default target URL in the IdP connection to Golf, or a default SP SSO URL for all IdP connections.
    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.

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