You can configure SP authentication policies to handle different authentication requirements for multiple IdP connections. Consider the following example.

Suppose you have configured the following use cases in an earlier version of PingFederate:

  • Two SP adapter instances on the Service Provider > Adapters screen:
    Instance Name Instance ID Extended Contract
    Sample sample subject and email
    Sample Delta sampleDelta subject and email
  • Three entries on the Service Provider > Target URL Mapping screen:
    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 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.0, you have the following new requirements:
  • Create new IdP connections to three new partners: Echo, Foxtrot and Golf.
  • Enforce multifactor authentication for users from Alpha, Charlie, Echo, and Golf through Bravo. Note that Bravo requires a user ID to be passed in from the original source and returns only the user ID when the users fulfill the multifactor authentication requirement.

The new required components are:

  • Two additional SP adapter instances (step 1):
    • Sample Echo to integrate with Echo's target application.
    • Sample Golf to integrate with Golf's target application.
  • Four new IdP connections (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 (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 (step 6).
  • Three SP authentication policies to enforce the multifactor authentication requirement (step 7, step 8, and step 12).
  • Three adapter mappings between the authentication policy contracts and the applicable SP adapter instances (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 (step 10):
  • SSO URLs for all partners (step 11).

Follow these steps to fulfill the new requirements:

  1. On the Service Provider > Adapters screen, create two new SP adapter instance:
    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 Service Provider menu, click Create New (under IdP Connections) and follow the IdP Connection wizard to create a SAML 2.0 IdP connection.
    2. On the IdP Connection > Browser SSO > SAML Profiles screen, select the SP-Initiated SSO check box.
    3. On the IdP Connection > Browser SSO > User-Session Creation > Identity Mapping screen, select No Mapping.
    4. Complete the rest of the connection configuration.
  3. Create IdP connections to Echo and Golf.
    1. On the Service Provider menu, click Create New (under IdP Connections) and follow the IdP Connection wizard to create a SAML 2.0 IdP connection to Echo (and then to Golf).
    2. On the IdP Connection > Browser SSO > SAML Profiles screen, select the SP-Initiated SSO check box.
    3. In 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. 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 the IdP Connection > Browser SSO > User-Session Creation > Target Session Mapping screen. The rest of the steps remain unchanged.

      This example does not use account linking.

    4. On the IdP Connection > Browser SSO > User-Session Creation > Attribute Contract screen, 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 Service Provider menu, click Create New (under IdP Connections) and follow the IdP Connection wizard to create a SAML 2.0 IdP connection.
    2. On the IdP Connection > Browser SSO > SAML Profiles screen, select the SP-Initiated SSO check box.
    3. On the IdP Connection > Browser SSO > User-Session Creation > Identity Mapping screen, select Account Mapping.
    4. On the IdP Connection > Browser SSO > User-Session Creation > Attribute Contract screen, enter samlEmail under Extend the Contract.
    5. In the IdP Connection > Browser SSO > User-Session Creation > Target Session Mapping screen, click Map New Adapter Instance and follow the Adapter Mapping & User Lookup configuration wizard to map the attributes from the assertion to the SP adapter instance Sample.
      Adapter Contract Source Value
      email Assertion samlEmail
      subject Assertion SAML_SUBJECT
    6. 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. Generally speaking:

    • You map attributes to authentication policy contracts from authentication policies (step 7 in this example).
    • You map attributes from authentication policy contracts to target applications through adapter mappings (step 9 in this example).
    1. On to the Service Provider > Policy Contracts screen, 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 screen, 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 screen, extend the authentication policy contract with an attribute for user's email address; for example, 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:

  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. On the Service Provider > Selectors screen, click Create New Instance.
    2. On the Type screen, 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 screen, enter PartnerIdpId in the HTTP Request Parameter Name field.
    4. On the Selector Result Values screen, 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; for example:

      Your selector instance should be similar to the following sample:

      HTTP Request Parameter Authentication Selector
  7. On the Service Provider > Policies screen, 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 screen, 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; for example:

      Your policies should be similar to the following samples:

  8. On the Policies screen, 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 screen, 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:

      (Note that this screen capture collapses the sso.charlie.local and sso.foxtrot.local policy paths for documentation presentation purpose.)

      When you go back to the Policies screen, your policies should be similar to the following samples:

    5. Click Save.
  9. Create adapter mappings.
    1. Go to the Service Provider > Adapter Mappings screen.
    2. 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:

      Each adapter mapping should be similar ot the following configuration:

      Tip:

      In essence, you are 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 the Service Provider > Target URL Mapping screen and 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:

      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.

    Optional: Based on the current configuration, you could remove the PartnerIdpId query parameter because it is not required. You could 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.

    Optional: Based on the current configuration, you could 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.

    Optional: Based on the current configuration, you could 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.

    Optional: Based on the current configuration, you could 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 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).

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