ZIdentity
Configuring PingFederate as an External IdP
This guide provides information on how to configure PingFederate as an external identity provider (IdP) for ZIdentity to facilitate single sign-on (SSO) to various Zscaler services for admin access management. You can configure PingFederate as an external IdP to enable SSO to ZIdentity using the Security Assertion Markup Language (SAML) authentication protocol. You can provision users to ZIdentity from PingFederate using System for Cross-domain Identity Management (SCIM) provisioning.
If you want to leverage step-up authentication, it is recommended to use OIDC-based integrations as most IdPs only support step-up authentication with the OIDC protocol.
Prerequisites
Ensure that you have a way to integrate an authenticated identity with PingFederate through IdP Adapters or Authentication Policies.
Configuring PingFederate as IdP for ZIdentity
To set up PingFederate as an IdP for ZIdentity:
- 1. Set up PingFederate as an IdP in ZIdentity.
- Log in to the ZIdentity Admin Portal.
- Go to Integration > External Identities.
Click Add Primary IdP (or Add Secondary IdP).
The Add Primary Identity Provider (or Add Secondary Identity Provider) window appears.
In the Add Primary Identity Provider (or Add Secondary Identity Provider) window, on the Basic tab:
Under the General section:
- Name: Enter a name for the IdP.
- Identity Vendor: Select PingFederate from the drop-down menu.
- Domain: Select the domain for which the IdP is responsible for authenticating the users. This allows the Zscaler service to display the correct IdP to authenticate an incoming user.
- Protocol: Select SAML.
- Status: Select Enabled.
Login ID: Enter an attribute that you want to be mapped with the Login ID attribute.
- If you are using
email
as the Login ID attribute, ensure that your email domain matches with one of the domains added to ZIdentity for thePrimary Email
attribute. - You can use any email domain for your primary email if you are using any attribute other than email as the source for the Login ID attribute.
- Ensure that the attribute you enter in the Login ID field matches exactly with the attribute received in the SAML assertions.
- If you are using
Under the SAML Configuration section:
- Input Method: Select Metadata URL.
IdP Metadata URL: Enter a random URL, and click Fetch.
The random URL is added for generating SP Metadata in the ZIdentity Admin Portal. This value is manually overridden in a subsequent step.
- Click Save.
The IdP is added to the ZIdentity Admin Portal.
Locate the IdP on the Primary Identity Provider (or Secondary Identity Provider) table, and click the Edit icon.
The Edit Primary Identity Provider (or Edit Secondary Identity Provider) window appears.
- In the Edit Primary Identity Provider (or Edit Secondary Identity Provider) window:
On the Basic tab, under the SAML Configuration section, locate SP Metadata, and click Download SP Metadata.
The SP Metadata is downloaded as an XML file.
On the Advanced tab:
- Enable SAML Signing Request.
- Signing Algorithm: Select the signing algorithm.
SP SAML Certificate: Click Download Certificate.
The SP SAML Certificate is downloaded.
- Enable Encrypted SAML Assertion.
SAML Encryption Certificate: Click Download Certificate.
The SAML Encryption Certificate is downloaded.
- Click Update.
- 2. Configure the SAML-based integration in PingFederate.
- Log in to the PingFederate server.
- Go to Applications > Integration > SP Connections.
Click Create Connection.
The SP Connection wizard appears.
In the SP Connection wizard:
- On the Connection Template tab:
Select Do Not Use a Template for This Connection.
- Select Next.
- On the Connection Type tab:
Select Browser SSO Profiles as Connection Template and SAML 2.0 as Protocol.
- Click Next.
- On the Connection Options tab:
Ensure that the Browser SSO option is selected.
- Click Next.
- On the Import Metadata tab:
- Metadata: Select the File option, and click Choose File.
Upload the SP Metadata file downloaded from the ZIdentity Admin Portal.
- Click Next.
- On the Metadata Summary tab:
Verify the Entity ID value.
- Click Next.
- On the General Info tab:
Review the connection details.
- Click Next.
- On the Browser SSO tab:
Click Configure Browser SSO.
The Browser SSO wizard appears.
In the Browser SSO wizard:
- On the SAML Profiles tab:
Select IdP-Initiated SSO and SP-Intiated SSO.
- Click Next.
- On the Assertion Lifetime tab:
- Minutes Before: (Optional) Modify the validity of the assertion before its issuance.
Minutes After: (Optional) Modify the validity of the assertion before its issuance.
- Click Next.
- On the Assertion Creation tab:
Click Configure Assertion Creation.
The Assertion Creation wizard appears.
In the Assertion Creation wizard:
- On the Identity Mapping tab:
Select Standard.
- Click Next.
- On the Attribute Contract tab:
Add the attributes that you want to send to ZIdentity.
These values are included in the SAML assertion, and they must match the values on the ZIdentity Admin Portal.
- Click Next.
On the Authentication Source Mapping tab, choose either to Map New Adapter Instance or Map New Authentication Policy based on your authentication configuration.
- Click Next.
- On the Summary tab:
Review the configured information.
- Click Done.
The Assertion Creation wizard is closed, and you are redirected to the Assertion Creation tab in the Browser SSO wizard.
- On the Identity Mapping tab:
- Click Next.
- On the Protocol Settings tab:
Click Configure Protocol Settings.
The Protocol Settings wizard appears.
In the Protocol Settings wizard:
- On the Assertion Consumer Service URL tab:
Ensure that the Endpoint URL value is populated from the SP Metadata file uploaded to PingFederate.
- Click Next.
- On the Allowable SAML Bindings tab:
Select POST method, and ensure that other methods are not selected.
- Click Next.
On the Signature Policy tab, do not make any changes, and click Next.
- On the Encryption Policy tab:
(Optional) Select The Entire Assertion to enable an encryption policy.
If you do not want to enable an encryption policy, ensure that the None option is selected.
- Click Next.
- On the Summary tab:
Review the configured information.
- Click Save.
The Protocol Settings wizard is closed, and you are redirected to the Protocol Settings tab in the Browser SSO wizard.
- On the Assertion Consumer Service URL tab:
- Click Next.
- On the Summary tab:
Review the configuration summary.
- Click Save.
The Browser SSO wizard is closed, and you are redirected to the SP Connection wizard.
- On the SAML Profiles tab:
- Click Next.
- On the Credentials tab:
Click Configure Credentials.
The Credentials wizard appears.
In the Credentials wizard:
- On the Digital Signature Settings tab:
Signing Certificate: Select the certificate that you want to use for signing the SAML assertion from the drop-down menu. If a signing certificate is not available, you must add a new certificate to the PingFederate server. To add a new certificate, click Manage Certificates.
The signing certificate is downloaded from the ZIdentity Admin Portal in a previous step.
- Click Next.
(Optional) On the Select XML Encryption Certificate tab:
If you want to encrypt assertions, select an algorithm and certificate for encryption using the following steps.
- Select an algorithm for Block Encryption and Key Transport.
Select a certificate. If a certificate is not available, click Manage Certificates to upload a new certificate.
- Click Next.
- On the Summary tab:
Review the configuration summary.
- Click Done.
The Credentials wizard is closed, and you are redirected to the Credentials tab in the SP Connection wizard.
- On the Digital Signature Settings tab:
- Click Next.
- On the Activation & Summary tab:
Review the configuration summary.
- Click Save.
The SP Connection for ZIdentity is configured and saved.
- On the Connection Template tab:
- Ensure that the configured SP Connection is displayed on the SP Connections page.
Click Select Action for the configured SP Connection, and click Export Metadata.
The Metadata Export wizard appears.
In the Metadata Export wizard, on the Export & Summary tab, click Export.
The Metadata file is downloaded.
- In the ZIdentity Admin Portal, go to Integration > External Identities.
Locate the IdP on the Primary Identity Provider (or Secondary Identity Provider) table, and click the Edit icon.
The Edit Primary Identity Provider (or Edit Secondary Identity Provider) window appears.
- In the Edit Primary Identity Provider (or Edit Secondary Identity Provider) window:
On the Basic tab, under the SAML Configuration section:
- Input Method: Click Upload Metadata.
- IdP Metadata: Click Upload IdP Metadata.
Click Update.
This replaces the random URL entered for the IdP Metadata URL field in a previous step.
- 3. Provision users for ZIdentity.
You can provision PingFederate users for ZIdentity using just-in-time (JIT) provisioning or System for Cross-domain Identity Management (SCIM) provisioning.
- JIT provisioning
- In the ZIdentity Admin Portal, go to Integration > External Identities.
Locate the IdP on the Primary Identity Provider (or Secondary Identity Provider) table, and click the Edit icon.
- The Edit Primary Identity Provider (or Edit Secondary Identity Provider) window appears.
In the Edit Primary IdP (or Edit Secondary IdP) window:
- Go to the Provisioning tab.
- Select Enable Just-in-time (JIT) Provisioning.
Map the ZIdentity user and group attributes with the appropriate PingFederate attributes as necessary. The mapping of the
Primary Email
attribute is mandatory as it is required for functionalities, such as password resetting and multi-factor authentication. By default, the following attributes in SAML assertions mapped with the corresponding user attributes in ZIdentity.Attribute in SAML Assertions Default ZIdentity User Attributes firstName First Name lastName Last Name displayName Display Name - If the external IdP is configured to send different attributes for
First Name
,Last Name
, orDisplay Name
, then you must map those attributes. For example, if the SAML assertion from the external IdP includesSurname
instead oflastName
, then you must map it with theLast Name
user attribute in ZIdentity. While mapping attributes, ensure that the attributes you enter in the Just-in-time Attribute field match exactly with the attributes that would be received in the SAML assertions.
- If the external IdP is configured to send different attributes for
- Click Update.
- SCIM provisioning
- In the ZIdentity Admin Portal, go to Integration > External Identities.
Locate the IdP on the Primary Identity Provider (or Secondary Identity Provider) table, and click the Edit icon.
- The Edit Primary Identity Provider (or Edit Secondary Identity Provider) window appears.
In the Edit Primary IdP (or Edit Secondary IdP) window:
- Go to the Provisioning tab.
- Select Enable SCIM Provisioning.
- Copy the SCIM Endpoint URL and Bearer Token value. This value is used in a subsequent step.
- (Optional) Map the SCIM attributes (e.g.,
addresses
) with the corresponding ZIdentity user attribute. This mapping is required only for attributes that need to be mapped to a custom user attribute in ZIdentity. To learn more about the SCIM attributes that require custom attribute mapping, see Understanding SCIM.
- Click Update.
- In the PingFederate server, go to Applications > Integration > SP Connections.
Locate the SP connection created for ZIdentity, and click the connection name to edit the configuration.
The SP Connection wizard appears.
- In the SP Connection wizard:
On the Connection Type tab, select Outbound Provisioning as Connection Template, and select SCIM Connector as Type.
The Outbound Provisioning tab is added to the SP Connection wizard.
On the Outbound Provisioning tab, click Configure Provisioning.
The Configure Channels wizard appears.
In the Configure Channels wizard:
On the Target tab:
- SCIM URL: Enter the SCIM Endpoint URL copied from the ZIdentity Admin Portal.
- SCIM Version: Select 2.0 from the drop-down menu.
- Authentication Method: Select OAuth 2 Bearer Token from the drop-down menu.
- Access Token: Enter the Bearer Token copied from the ZIdentity Admin Portal.
- Click Next.
- On the Manage Channels tab:
Click Create.
The Channel wizard appears.
To learn more about channels in PingFederate, refer to the PingFederate Technical documentation.
In the Channel wizard:
- On the Channel Info tab:
- Channel Name: Enter a name for the channel.
- Max Threads: Enter
1
. Timeout (Secs): Enter
60
.- Click Next.
- On the Source tab:
Active Datastore: Select the datastore from the drop-down menu.
- Click Next.
On the Source Settings tab, leave the configuration to its default settings, and click Next.
- On the Source Location tab:
- Base DN: Enter the Base DN for your data store.
- Under the Users section:
- Group DN: Enter the Group DN for the users in your data store.
- Enable Nested Search.
Under the Groups section:
- Group DN: Enter the Group DN for groups in your data store.
- Enable Nested Search.
- Click Next.
- On the Attribute Mapping tab:
- Ensure that the userName filed is mapped to userPrincipalName attribute.
Map any other attributes as necessary. The mapping of the
Email
attribute is mandatory as it is required for functionalities, such as password resetting and multi-factor authentication.- Click Next.
- On the Activation & Summary tab:
Channel Status: Select Active.
- Click Done.
The Channel wizard is closed, and you are redirected to the Manage Channels tab.
- On the Channel Info tab:
- Click Done.
The Configure Channels wizard is closed, and you are redirected to the Outbound Provisioning tab.
- Click Next.
On the Activation & Summary tab, review the configuration, and click Save.
- JIT provisioning