Configuring the Zscaler Service to Synchronize Data


Configuring the Zscaler Service to Synchronize Data

Do the following to configure the Zscaler service to synchronize user information with a directory server:

  1. Complete the prerequisites.
  2. Configure the Zscaler service.

To enable the Zscaler service to synchronize user data from your directory server, ensure that your directory servers and firewall are configured as follows:

  • On your directory server, grant the Zscaler service read-only access on a specific port. (Zscaler will provide the IP addresses.)
  • Configure the directory server to allow the service to connect to the appropriate ports when the service performs an LDAP Bind.

Before you configure the service, do the following:

  • Ensure that all your email domains have been added to your Zscaler account. The service synchronizes data only from the configured domains. To view the domains, log in to the service portal and go to Administration > Settings > Company Profile > Organization tab.
  • Ensure that you have the following:
    • The IP address/hostname of your directory server
    • The Distinguished Name (DN) of a user with permission to “bind” to (or query) the directory server. The account does not require privileged access.
    • Which groups you want to synchronize
    • The location of the User and Group objects in your directory structure.

If you are synchronizing data from an Active Directory server, see additional guidelines.

  • The Zscaler service can synchronize user information from one forest in an organization. If your organization has multiple forests, you can set up an AD proxy. Otherwise, Zscaler recommends integrating with a SAML provider.
  • The Zscaler service can synchronize data from multiple domains, as long as they are all registered with Zscaler support.
  • The Zscaler service does not support nested groups. You must manually identify specific group names within each nested group and add them to the group filter.

To configure the service to synchronize user data with a directory server, log in and do the following:

  1. Enable Authentication.
  2. Use one of the following methods to define the synchronization settings of your directory server:
    • Setup Wizard – The Setup Wizard walks you through synchronizing user data from an enterprise directory server to the Zscaler service. This is the recommended method. It validates your entries and allows you to check the data before it is synchronized to the service. After you complete the Wizard, the parameters are stored and displayed on screen.
      See Run the Setup Wizard.

​​​​​​OR

  1. Configure the authentication method:
    • LDAP BIND is the default authentication method when users are synchronized from a directory server. It is configured when you perform the preceding step (that is, when you run the Setup Wizard or define synchronization settings).
    • One-Time Token/One-Time Link
      Note that if you use either a one-time token or one-time link to authenticate users whose information was synchronized from a directory server, the passwords are stored on the Zscaler database and not on the directory server.
    • SAML (Security Assertion Markup Language)

To enable authentication for a location:

  1. Log in to the service and go to Administration > Resources > Location.
  2. Edit the location for which you are enabling authentication.
  3. Select Enforce Authentication.
  4. Click Save and activate the change.

You can configure the service to automatically synchronize user data from the directory server daily, weekly or monthly. If the directory server is unavailable at the scheduled time, the service will attempt to synchronize at the next scheduled time.

Zscaler recommends that you use the Set Up wizard to define synchronization settings. The wizard validates your entries and allows you to check the data before it is synchronized to the service. After you complete the wizard, the parameters are stored and displayed on this tab.

  1. Go to Administration > Authentication > Authentication Settings.
  2. From Directory Type, choose Active Directory or OpenLDAP.
  3. From Authentication Frequency, choose how often users are required to authenticate to the Zscaler service. If you select Custom, specify 1 to 180 days.
  4. Click Setup Wizard. Following are the wizard steps. 

NOTE: In each step, you can click View Setup Log at any time to review the settings you defined in the preceding steps and any errors or warnings.

In this step, specify the authentication agent and define the settings for the directory server. Zscaler highly recommends that you enable LDAP over Secure Sockets Layer (SSL) to secure LDAP communications between the service and your directory server.

The service can synchronize data for up to two sets of users. For example, it can synchronize data from two directory servers, one in Europe and another one in the U.S., if they have different user, group, and department information. Configure the service to synchronize from a secondary directory server only if it does not have duplicate user or group information. Do not set up a secondary server for redundancy.

Define the Directory Server settings by completing the fields below, and then click Next:

  • Authentication Agent Hosting: Select one of the following:
    • Enterprise: Select this if your organization has a ZAB installed.
    • Cloud: Select this if the CA queries your directory server directly.
  • Directory Server Address: You can enter the IP address of a directory server or to provide fault tolerance and resiliency against directory server failures, you can enter an FQDN that points to the IP addresses of  multiple directory servers. If you enter an FQDN and DNS resolution returns multiple IP addresses, Zscaler automatically ignores the servers that are inactive or not available and synchronizes with a server that is available.
  • Secure LDAP: Select this check box to use SSL encryption for the LDAP communications. Ensure that an SSL certificate is installed on your directory server. Zscaler highly recommends that you enable this option.
  • Directory Type: Choose your directory type.
  • Port: Specify the port to which the service connects when it synchronizes data. Default values are:
    • 3268 – Used to connect to the Global Catalog of an AD server.
    • 3269 – Used to connect to a Global Catalog AD server over a secure connection using SSL.
    • 389 – Used to connect to an LDAP server. AD default port for listening.
    • 636 - Used to connect to an LDAP server over a secure connection using SSL.

If your organization is synchronizing multiple domains from an AD server, select either port 3268 (non-secure) or 3269 (secure) so the Zscaler service can access the Global Catalog. The Global Catalog contains all domain objects in an AD forest.

If your organization uses custom ports, specify them accordingly.

  • Secondary Configuration: Enable this to synchronize with two servers that have different sets of user data. Do not use this option to synchronize the service with two directory servers that have duplicate information. When the Directory Name field appears, enter a name for the first server.

Step 1

When a client, such as the Zscaler service, connects to a directory server, the server performs a BIND operation where it authenticates the client and if this is successful, allows the client to access the server. The directory server can require the client to enter a Distinguished Name (DN) and password, or it can allow the client to perform the query anonymously, without requiring credentials. In this step, specify whether the directory server allows anonymous access. If it does not, enter the DN and password required to access the server.

Do one of the following, and then click Next:

  • Click the Use anonymous authentication checkbox, if the directory server allows anonymous access. Ensure that this option is enabled on your directory server.

OR

  • Enter the following information:
    • Bind DN: Enter the DN of an administrator account that has permission to query the directory server. Use one of the following formats:
      • domain\user For example: zscaler\admin
      • LDAP syntax, for example: cn=admin,cn=users,dc=zscaler,dc=net
    • Bind Password: The password of the administrator account specified in the Bind DN field.

Step 2

At this point, the wizard has successfully connected to the directory server and pre-populated the Base DN field. The Base DN specifies the location or branch of the directory where the service will begin searching for users, groups and departments. The service only retrieves objects from the branch that is specified in the Base DN field.

Do the following, and then click Next:

  • Base DN: By default, this field contains the DN of the top of the tree (for example, cn=<domain>, cn=<com>). Depending on the directory structure, this may return more results than are desired. Conversely, providing a narrower starting search point on the tree may exclude the desired users and groups. Before populating this field, examine your directory structure to identify under which “branches” the desired users and groups are located and enter the base DN as appropriate. To start the search from another location in the directory, select it from the list or enter its DN.
  • Pagination: Select one of the following:
    • Auto (Recommended): The Zscaler service will detect if pagination is supported by your directory server. If the directory server supports pagination, it will page results that exceed 1000 items. If not, the directory server will return the first 1000 items only.
    • Enabled: Enables the directory server to page results that exceed 1000 items.
    • Disabled: The directory server will return the first 1000 items only.

Step 3

In this step, specify which attributes represent the user information required by the service. You can define filters, as well, to narrow down the results.

Note the following:

  • Zscaler highly recommends that you use an "LDAP browser," such as Apache Studio Directory or Softerra, to view several actual users and confirm which attributes are being used to identify name, email address, department, and group information.
  • If you are synchronizing information from an LDAP server and your organization uses custom LDAP attributes, consult your LDAP administrator to determine which attributes to use.

Do the following, and then click Next:

  1. To discover the LDAP attributes needed by service, complete the Lookup Parameters section and click Lookup User Entry. The service will query the directory for the username. If it exists, the wizard will display the user’s attributes in the Lookup Results panel.
    • Lookup Parameters: Choose one of the following lookup methods and enter a value in the text field below the list. Ensure that the value exists in the directory.
      • Auto: This is the easiest and recommended method. Enter an email address, login name, DN, or LDAP attribute (for example:objectClass=User).
      • Email Address
      • Windows Login
      • Distinguished Name
      • Specify an LDAP Attribute
    • Click Lookup User Entry. Upon a successful lookup, the user's or group's attributes that were retrieved from the directory appear in the Lookup Results panel.
  2. In the Attribute Fields section, specify the names of the attributes that represent the user's email address, full name, group, and department, and define filters as well. Zscaler provides granular filters so you can synchronize only the relevant users, groups and departments to the service.

Use the Group Search Filter and User Search Filter to narrow down the user and group objects that are returned. Here, you can define a filter string that will locate only the users and groups that you need, such as users who belong to specific groups. Again, Zscaler strongly recommends that you use an LDAP browser to query filters prior to synchronizing user data with the directory server. 

Specify the following:

  • User Login: Specify the attribute that represents the login name that users enter when they log in to the service. This attribute is used to verify the login name that a user enters when logging in to the Zscaler service for authentication. Following are some guidelines for the login name:
    • The value of the login name must be in the form of an email address, though it does not have to be a valid email address.
    • It must be unique and the domain name must belong to the organization.
    • If the value is not an email address, the service creates an email address by appending the domain name to it, if your organization has registered a single domain on the service. If your organization has registered multiple domains and the value is not an email address, synchronization will fail.
    • Zscaler recommends that you use userPrincipalName, regardless of the number of domains hosted by the Zscaler service. Use sAMAccountName only if you have one domain hosted by the Zscaler service. Otherwise, you can use proxyAddressesuserPrincipalName or mail.
  • User Full Name: Specify the attribute that represents user names. For example:cn or displayName. The Zscaler service displays the value in this attribute in the Who dialog that appears when administrators create policies.
  • User Search Filter: Use this filter to narrow down the user objects that the service returns after the synchronization. You can enter a filter string to locate specific users only, such as users who belong to a specific group. For example, enter objectClass=person to narrow down the data to persons and not computers.
  • Department Membership: This attribute is used to populate the Department field in the reports produced by the Zscaler service. You can specify any attribute that identifies the information that should appear in the Department field. For example, you can use department or ou.
  • Group Name: Specify the attribute that represents group names. For example:cn.
  • Group Membership: Specify the attribute that identifies the group membership. For example: memberOf.
  • Group Search Filter: Use this filter to narrow down the group objects that the service returns after the synchronization. Define filters to narrow down the results to only the groups to which you want to apply policies. The service synchronizes up to 16 groups per user.
    • To import only one group, use the following filter:
      (&(objectclass=group)(cn=<groupname>*))
    • To import multiple groups, use the following filter:
      (&(objectclass=group)(|(cn=<groupname1>*)(cn=<groupname2>*)))

NOTE:

  • Replace <groupname>,<groupname1>, and <groupname2> with the actual group name in the directory server.
  • The asterisk ( * ) is required, so the filter automatically completes the Common Name (cn) value.
  • Following is an example of a filter that will import the following three groups: vips, standard users and advanced users.
    • (&(objectClass=group)(|(cn=vips*)(cn=standard users*)(cn=advanced users*)))
  • Following is an example of a filter that will import all groups that begin with zscaler:
    • (&(objectClass=group)(cn=zscaler*))

& character means that all criteria must be true
| character means that at least one criteria must match

After you click Next, the wizard saves the parameters and starts synchronizing.

NOTE: If you selected Secondary Configuration in the first step, clicking Next repeats steps 2 – 4 for the second directory server.

In the Synchronization window, the wizard displays the synchronization results, as shown in the following figure. Click any of the numbers in the AddedModifiedRemovedTotal Before, and Total After fields to view and search through the entries discovered during the synchronization.

Step 5

Verify whether the user information was synchronized correctly, and then click Next:

  1. If your organization has a ZAB, enter its URL or IP address in the Authentication Agent Address field.
  2. Verify the User Authentication Filter
    Unlike the User Search Filter and Group Search Filter, the service uses this filter when it authenticates a user, not when it synchronizes users from the directory server.
  3. Enter a user's credentials to ensure that the retrieved attributes are correct. For example: 
    Test User Login: User@example.com
    Test User Password: Password1234*
  4. Click Check Authentication.

Select Finish to exit the wizard.

Zscaler strongly recommends that you use the Setup Wizard to define your synchronization settings. It walks you through the process and validates your entries. But if you want to define or edit the settings without using the wizard, do the following:

  1. Go to Administration > Authentication > Authentication Settings.
  2. From Directory Type, choose Active Directory or OpenLDAP.
  3. Click Advanced Configuration and complete the following:
    • From the Synchronization Frequency menu, choose one of the following:
      • Manual: Choose this to synchronize only when you click Sync Now.
      • Daily: Choose this to synchronize every 24 hours at midnight in the organization's time zone.
      • Monthly: Choose this to synchronize on the first day of every month at midnight in organization's time zone.
      • Weekly: Choose this to synchronize every Sunday at midnight in the organization's time zone.
    • Authentication Agent Hosting:
      • In-the-Cloud: Select this if the CA queries your directory server directly.
      • Enterprise-Hosted: Select this if your organization has a ZAB installed.
        • Enter the ZAB's IP address in the Authentication Agent URL field.
    • Enable Second Directory: Choose this to synchronize with two servers that have different sets of user data. Do not use this option to synchronize the service with two directory servers that have duplicate information. If you enable this option, complete the Directory Server Details for both Directory # 1 and Directory # 2.
    • In Directory Server Details, complete the following. If you turned on Enable Second Directory, ensure you complete the fields for both Directory # 1 and Directory # 2.
      • Directory Name: Enter a name.
      • Server Address: You can enter the IP address of a directory server or to provide fault tolerance and resiliency against directory server failures, you can enter an FQDN that points to the IP addresses of multiple directory servers. If you enter an FQDN and DNS resolution returns multiple IP addresses, Zscaler automatically ignores the servers that are inactive or not available and synchronizes with a server that is available.
      • Secure Access: Turn on to use SSL encryption for LDAP communications. Ensure that an SSL certificate is installed on your directory server. Zscaler highly recommends that you enable this option.
      • Port: Specify the port to which the service connects when it synchronizes data. Default values are:
        • 3268 – Used to connect to the Global Catalog of an AD server.
        • 3269 – Used to connect to a Global Catalog AD server over a secure connection using SSL.
        • 389 – Used to connect to an LDAP server. AD default port for listening.
        • 636 - Used to connect to an LDAP server over a secure connection using SSL.

If your organization is synchronizing multiple domains from an AD server, select either port 3268 (non-secure) or 3269 (secure) so the Zscaler service can access the Global Catalog. The Global Catalog contains all domain objects in an AD forest.

If your organization uses custom ports, specify them accordingly.

  • In Connection Parameters, complete the following:
    • Advanced Base DN (This field appears only if using Open LDAP. Proceed to Base DN if using Active Directory): The users and groups that you want to synchronize may be in separate "branches" of your directory structure. If you enable this, complete the following fields.
      • User Base DN: By default, this field contains the DN of the top of the tree (for example, cn=, cn=). Depending on the directory structure, this may return more results than are desired. Conversely, providing a narrower starting search point on the tree may exclude the desired users and groups. Before populating this field, examine your directory structure to identify under which 'branches' the desired users and groups are located and enter the base DN as appropriate. To start the search from another location in the directory, select it from the list or enter its DN.
      • Group Base DN: Specify the DN of the branch or location where the group objects are located.
    • Base DN (If using Open LDAP, this option disappears if you enable Advanced Base DN above. Proceed to the next field, Pagination, if you enable Advanced Base DN.): By default, this field contains the DN of the top of the tree (for example, cn=<domain>, cn=<com>). Depending on the directory structure, this may return more results than are desired. Conversely, providing a narrower starting search point on the tree may exclude the desired users and groups. Before populating this field, examine your directory structure to identify under which “branches” the desired users and groups are located and enter the base DN as appropriate. To start the search from another location in the directory, select it from the list or enter its DN.
    • Pagination: Select one of the following:
      • Auto (Recommended): The Zscaler service will detect if pagination is supported by your directory server. If the directory server supports pagination, it will page results that exceed 1000 items. If not, the directory server will return the first 1000 items only.
      • Enabled: Enables the directory server to page results that exceed 1000 items.
      • Disabled: The directory server will return the first 1000 items only.
    • Anonymous Authentication: Do one of the following:
      • Turn on this option if the directory server allows anonymous access. Ensure that this option is enabled on your directory server.
      • Leave this option off if the directory server does not allow anonymous access, and complete the following fields.
        • Bind DN: Enter the DN of an administrator account that has permission to query the directory server. Use one of the following formats: 
          domain\user For example: zscaler\admin
          LDAP syntax, for example: cn=admin,cn=users,dc=zscaler,dc=net
        • Bind Password: The password of the administrator account specified in the Bind DN field. 
  • In Attribute Fields, complete the following:
    • Login Attribute: Specify the attribute that represents the login name that users enter when they log in to the service. This attribute is used to verify the login name that a user enters when logging in to the Zscaler service for authentication. Following are some guidelines for the login name:
      • The value of the login name must be in the form of an email address, though it does not have to be a valid email address.
      • It must be unique and the domain name must belong to the organization.
      • If the value is not an email address, the service creates an email address by appending the domain name to it, if your organization has registered a single domain on the service. If your organization has registered multiple domains and the value is not an email address, synchronization will fail.
      • Zscaler recommends that you use userPrincipalName, regardless of the number of domains hosted by the Zscaler service. Use sAMAccountName only if you have one domain hosted by the Zscaler service. Otherwise, you can use proxyAddressesuserPrincipalName, or mail.
    • User Display Name Attribute: Specify the attribute that represents user names. For example: cn or displayName. The Zscaler service displays the value in this attribute in the Who dialog that appears when administrators create policies.
    • Member in Group (This field appears only if using Open LDAP): Specify the attribute in the group object that identifies the group membership. For example: memberOf
    • User in Member (This field appears only if using Open LDAP): Specify the user attribute present in the group entry.
    • Group Membership Attribute (This field appears only if using Active Directory):Specify the attribute that identifies the group membership. For example: memberOf.
    • Group Attribute Name: Specify the attribute that represents group names. For example: cn.
    • Department Name Attribute: This attribute is used to populate the Department field in the reports produced by the Zscaler service. You can specify any attribute that identifies the information that should appear in the Department field. For example, you can use department or ou.
  • In Search, complete the following:
    • Group Search Filter: Use this filter to narrow down the group objects that the service returns after the synchronization. Define filters to narrow down the results to only the groups to which you want to apply policies. The service synchronizes up to 16 groups per user.
      • To import only one group, use the following filter: (&(objectclass=group)(cn=<groupname>*))
      • To import multiple groups, use the following filter: (&(objectclass=group)(|(cn=<groupname1>*)(cn=<groupname2>*)))

        NOTE:
        • Replace <groupname>,<groupname1>, and <groupname2> with the actual group name in the directory server.
        • The asterisk ( * ) is required, so the filter automatically completes the Common Name  (cn) value.
        • Following is an example of a filter that will import the following three groups: vips, standard users and advanced users.
          • (&(objectClass=group)(|(cn=vips*)(cn=standard users*)(cn=advanced users*)))
        • Following is an example of a filter that will import all groups that begin with zscaler:
          • (&(objectClass=group)(cn=zscaler*))

& character means that all criteria must be true
| character means that at least one criteria must match
    • User Search Filter: Use this filter to narrow down the user objects that the service returns after the synchronization. You can enter a filter string to locate specific users only, such as users who belong to a specific group. For example, enter objectClass=person to narrow down the data to persons and not computers.
    • Advanced Search Filter: By default, Zscaler uses the User Search Filter for synchronizing and authenticating users. Enable this if you want to use a separate search filter for the authentication process (for example, a search filter that searches using non-email format attributes).
    • Search Filter: Enter the user search filter that Zscaler will use only during the authentication process.