How do I configure SAML?

Below are the tasks to enable the Zscaler service to use SAML for provisioning and authenticating users. Click to learn more about each task:

Before you configure the Zscaler service to use SAML for provisioning and authentication, ensure that you do the following:

  • Obtain and configure an IdP, such as ADFS, Okta or OneLogin. See below for links to configuration examples.
  • Obtain the SSL certificate of the IdP. You will upload this certificate to the Zscaler service portal when you configure the service to use SAML.
  • Export the XML meta-data from the IdP. You will use information from the metadata when you configure the service to use SAML.
  • If you are using PAC files to forward traffic to the Zscaler service, add the redirected URL to the bypass list in the PAC files otherwise the authentication will fail.  This is due to the browser trying to reach the authentication URL via the Zscaler service but the current user is not yet authorized to use the service so the request never passes through the Zscaler node.

Click below for configuration examples that provide instructions for adding the Zscaler service to an IdP.

Complete the steps below to configure the service to use SAML for provisioning and authentication. The steps below explain how to download the Zscaler certificate, which you can upload to your IdP.

  1. Go to Administration > Authentication > Authentication Settings.
  2. Authentication Frequency: Choose how often users are required to authenticate to the Zscaler service. If you select Custom, the Custom Authentication Frequency (days) field will appear below.
    • Custom Authentication Frequency (days): Specify 1 to 180 days.
  3. Authentication Type: Choose SAML, and then click Configure SAML.
  4. In the Edit SAML window, do the following:
    • SAML Portal URL: Enter the URL of the SAML portal to which users are sent for authentication. Ensure that it is publicly resolvable if you want users to authenticate from the Internet. Additionally, ensure that it is protected using HTTPS. You can obtain this information from the XML meta-data of the IdP. 

For example, for ADFS, you can obtain it from the line:
SingleSignOnService Binding=....HTTP-POST* Location="")
For OneLogin, you can copy it from the SAML Endpoints URL field referenced in step 5 of Adding the Zscaler Service as an Application in Configuration Example: OneLogin.

  • Login Name Attribute: Enter the LDAP attribute that maps to the login name that users enter when they authenticate to the Zscaler service. Typically, it is NameID. (Note that NameID is entered as one word, with no spaces.) This field is case sensitive.
  • Public SSL Certificate: Click Upload, and then click Choose File to navigate to the public certificate that is used to verify the digital signature of the IdP. This is the certificate you downloaded from the IdP. The certificate must in base-64 encoded PEM format. The file extension must be .pem and have no other dots (.) in the file name.
  • Sign SAML Request: Enable if the Identity Provider expects the SAML request to be signed. The Signature Algorithm field will appear below.
    • Signature Algorithm: Choose whether to sign the SAML Request with an SHA-1 (160-bit) hashing algorithm or with an SHA-2 (256-bit) hashing algorithm. Note that if you are reconfiguring SAML because the certificate expired, Zscaler recommends that you select the certificate with the later expiration date.
  • Request Signing SSL Certificate: Choose which certificate you want to use for signing SAML requests.
  • SP’s Public Certificate: Click Download to export the Zscaler certificate that you will upload to the IdP when you configure it.
  • Service Provider’s Metadata:  Optionally, click Download to export the metadata of the Zscaler service. The metadata advertises the Zscaler SAML capabilities and is used for auto-configuration. Some IdPs require importing of the metadata to configure the Zscaler service as a service provider.
  • Enable SAML Auto-Provisioning: Enable to provision users on the service. If you enable SAML auto-provisioning, the following fields will appear below:
    • User Display Name Attribute: Specify the LDAP attribute that maps to the user name. Typically, this is displayName. This is case-sensitive.
    • Group Name Attribute: Specify the LDAP attribute that maps to the group name. Typically, this is memberOf. This is case-sensitive.
    • Department Name Attribute: Specify the LDAP attribute that maps to the department name. Typically, this is department. This is case-sensitive.
  • Enable SCIM-Based Provisioning: Enable to activate SCIM based provisioning for users on the service. If you enable SCIM based provisioning, the following fields will appear below:
    • Base URL: This is the Base URL for the SCIM server. This is always https://scim.<zscloud_name>/<orgid>/scim
    • Bearer Token: This token is used by the SCIM client to make authenticated API calls to the Zscaler SCIM server.
    • Generate Token: Click this button to generate a new bearer token.
      To learn more about SCIM, see About SCIM.
  1. Click Save to exit the window.
  2. Click Save and activate the change.

For background information on using SAML, see About SAML.

For help with troubleshooting SAML, see SAML Troubleshooting Guidelines.