icon-zdx.svg
Digital Experience Monitoring (ZDX)

Admin SAML SSO Configuration Guide for PingFederate

This guide illustrates how to configure Ping Identity's PingFederate server as the identity provider (IdP) for ZDX.

Prerequisites

Ensure that you have the following before you start configuring PingFederate as your IdP:

  • PingFederate admin account

  • To download the Zscaler Internet Access Connector:

    1. Go to the PingFederate Server Add-Ons page.

    2. Under SaaS Connectors, download Zscaler Internet Access Connector 1.1.

    3. Unzip the connector folder to extract the pf-zscaler-zia-quickconnection-1.1.jar file.
    4. Add the pf-zscaler-zia-quickconnection-1.1.jar file to PingFederate > Server > default > deploy folder.
    Close

  • To export your PingFederate signing certificate on the PingFederate admin console:

    1. Log in to your PingFederate administrative console.

    2. Go to Security > Signing & Decryption Keys & Certificates.

    3. Click Select Action on the certificate you want to use.

    4. Click Export.

    5. On the Export Certificate tab, click Next.

    6. On the Export & Summary tab, click Export.

    7. Rename the downloaded certificate's extension to .pem.
    8. Save this certificate for when you are ready to add PingFederate as an IdP in ZDX.
    Close

  • When configuring IdPs, the following information might be required for ZDX.

    • ACS URL:

    For ZDX Cloud:

    https://admin.zdxcloud.net/zdx/idp-auth

    For ZDX Beta Cloud:

    https://admin.zdxbeta.net/zdx/idp-auth
    • Download the SAML SSL certificate from the IdP. It must be in Base-64 encoded PEM format.
    • Entity ID:

    For ZDX Cloud:

    https://admin.zdxcloud.net

    For ZDX Beta Cloud:

    https://admin.zdxbeta.net

    If you have a domain defined on multiple ZIA clouds, enter the ZIA cloud name that is associated with ZDX in the Relay State field (for example, zscalertwo.net) for each application.

    You must also create admin accounts for your organization's admins. To learn more, see Adding ZDX Admins.

    Close

  • To download the XML Metadata from ZDX:

    1. Sign in to ZDX as an administrator.
    2. Go to Administration > Administrator Management > Administrator Management.
    3. Click Download.

    Remember where you saved the metadata as you will upload it for creating a service provider (SP) connection.

    To learn more, see Configuring SAML for ZDX Admins.

    Close

Configuring SAML SSO on Zscaler Services

You need to register PingFederate as an IdP in Zscaler Services for SAML Single Sign-On (SSO).

To add PingFederate as an IdP in ZDX:

  1. If you haven't renamed your certificate from the prerequisites step, rename your certificate's extension to .pem.
  2. Upload your IdP signing certificate as described in Configuring SAML SSO for ZDX Admin.
  3. Click Save.
  4. Save your configuration changes by activating the changes.

Configuring a Service Provider Connection on PingFederate

To configure a Service Provider (SP) Connection on the PingFederate administrative console:

  1. Verify SAML 2.0 entity ID:
    1. Go to System > Server > Protocol Settings > Federation Info.
    2. In the SAML 2.0 Entity ID field: Enter a name for PingFederate to use when SAML applications need to identify it.
    3. Click Save.
  2. Create a service provider connection:
    1. Use the SP Connections shortcut or go to Applications > Integration > SP Connections.

    2. Click Create Connection.

    3. In the Create Connection wizard, configure:

        1. Select Use a template for this connection.
        2. For Connection Template, select Zscaler ZIA Connector.
        3. For Metadata File, upload your metadata file into the Metadata File field.

        Click Next.

        SP Connection Connection Template

        Close

      • Ensure the Browser SSO Profiles checkbox is selected, then click Next.

        SP Connection Connection Type

        Close

      • Ensure the Browser SSO checkbox is selected, then click Next.

        Connection Options

        Close

      • On the General Info tab:

        • Partner's Entity ID (Connection ID): Verify the Partner's Entity ID.
        • Connection Name: Enter a connection name. This might be pre-populated and can be revised to your preference.
        • Base URL: Verify the Base URL. You must append :443 to the end of your base URL.

        For example, if your base URL is https://login.zscaler.net, then your new base URL is:

        https://login.zscaler.net:443

        Click Next.

        Configure General Info

        Close
        1. On the Browser SSO page, click Configure Browser SSO.
        2. On the Assertion Creation page, click Configure Assertion Creation.
        3. On the Authentication Source Mapping page, click Map New Authentication Policy.

        4. On the Authentication Policy Contract tab, select subject for the Authentication Policy Contract field.

          This allows the authentication to be connected to policies. If required, you can configure the contract attribute that is applicable to you.

          Click Next.

        5. On the Mapping Method page, select Retrieve Additional Attributes from a data store -- includes options to use alternate data stores and/or a failsafe mapping.

          Click Next.

        6. On the Attribute Sources & User Lookup tab, click Add Attribute Source.

        7. On the Data Store page:

          • Attribute Source Description: Enter a description for the Attribute Source.
          • Active Data Store: Select PingDirectory.

          Click Next.

        8. On the LDAP Directory Search page:

          • Base DN: Enter ou=Zscaler Users,dc=example,dc=com.
          • Search Scope: Select Subtree from the drop-down menu.
          • Attributes to select from the search:
            • Root Object Class: Select <Show All Attributes>.
            • Attribute: Select mail.
            • After mail is added, click Add Attribute next to it.

          Click Next.

        9. On the LDAP Filter page, for the Filter field, enter uid=${subject}.

          Click Next.

        10. On the Attribute Contract Fulfillment page:

          • SAML_Subject: Select LDAP (pd).
          • Value: Select mail.

          Click Next.

        11. On the Summary page, click Done after you verify your attribute source configuration.

        12. On the Attribute Sources & User Lookup page, click Next after you verify your data store to supply user information in the SAML assertion to the SP.

        13. On the Failsafe Attribute Source page, select Abort the SSO Transaction.

          Click Next.

        14. Click Done after reviewing your Authentication Source Mapping configuration.

        15. Click Done after reviewing your Summary.

        16. On the Assertion Creation page, click Next.

        17. On the Protocol Settings page, click Next.

        18. On the Summary page, click Done to save your configuration.

        Close

        1. On the Credentials page, click Configure Credentials.

        2. Select your Signing Certificate.

          Click Done.

        Close

Initiate SSO

ZDX and PingFederate support Identity Provider- and Service Provider-initiated single sign-on. PingFederate's documentation provides information for invoking IdP initiated SSO. Refer to the PingFederate documentation.

When using IdP-initiated SSO, ZDX requires the cloud name (e.g., zscalerthree.net) passed through the SAML Relay State if you have a domain defined on multiple ZIA clouds. Zscaler recommends using the SAML Relay State in a single ZIA cloud deployment to avoid any disruption if a second ZIA cloud is added in the future. PingFederate supports this by passing the necessary Relay State value by using the TargetResource query parameter in the /idp/startSSO.ping application endpoint.

For example (the green text shows where to insert the ZIA Cloud Name associated with ZDX):

https://{PingFederate hostname}/idp/startSSO.ping?PartnerSpId={ZDX Connection ID}&TargetResource=zscalerthree.net
Related Articles
Admin SAML Configuration Guide for AD FS 3.0Admin SAML Configuration Guide for Azure Active DirectoryAdmin SAML Configuration Guide for OktaAdmin SAML SSO Configuration Guide for PingFederate