icon-zia.svg
Secure Internet and SaaS Access (ZIA)

Deploying a Zscaler Authentication Bridge

The Zscaler Authentication Bridge (ZAB) is a virtual machine (VM) that you can use to provision and authenticate users. To learn more, see About the Zscaler Authentication Bridge.

If you're subscribed to multiple ZABs, only one ZAB can synchronize your users. For example, you can deploy two ZABs, and the Zscaler service automatically uses the healthy one to sync users. If you also want to use the ZAB for authentication, ensure the configured ZAB URL can address both ZABs. During deployment, you can create a DNS entry for the ZAB. The user is redirected to the URL during the password authentication phase. You can implement a round-robin DNS or put the ZABs behind a load balancer to achieve an active deployment.

New or clean deployment of ZAB requires VM image running on Zscaler OS version 24.

Requirements

Ensure you have the following to deploy the ZAB:

  • Hypervisor VMware ESX/ESXi version 6.0 and later.
  • A VM with:
    • 2 GB of RAM minimum. This increases with the number of users.
    • 64-bit Xeon CPU. Two cores assigned to the VM.
    • 1 network interface with a static IP address. This IP address is used for control and data connections to the Zscaler cloud and to connect to the directory server. Your administrator can also use it to make an SSH connection to the VM.
  • A ZAB subscription.
  • Super admin access for the ZIA Admin Portal.
  • Log in information for your directory server.

Prerequisites

Ensure your outbound firewall is configured to allow the necessary connections. The ZAB requires outbound connections to the Zscaler service. To view the firewall requirements, go to:

https://config.zscaler.com/<Zscaler Cloud Name>/zab

The <Zscaler Cloud> depends on the URL you use to log in to the Zscaler service. For example, if you log in to admin.zscalerbeta.net, then go to https://config.zscaler.com/zscalerbeta.net/zab. To learn more, see What is my cloud name for ZIA?

Deploying a ZAB

Only super admins can deploy a ZAB.

To deploy a ZAB:

  • To verify your organization's ZAB subscription:

    1. Go to Administration > Company Profile.
    2. Click the Subscriptions tab.
    3. Verify that your organization is subscribed to Zscaler Auth Bridge.
    Close
  • 2. Add the ZAB using the ZIA Admin Portal.
  • 3. Download the ZAB virtual machine (VM).

  • The ZAB uses an SSL certificate to authenticate itself to the Zscaler service.

    To download the ZAB SSL certificate:

    1. Go to Administration > Authentication Settings.
    2. Click the Authentication Bridges tab.
    3. In the SSL Certificate column of the ZAB, click Download.
    Close

  • To configure the network settings of the ZAB:

    1. On the ZAB, log in with the following default credentials:
    2. Switch to a superuser, by entering the following command:
    sudo su -
    1. Enter the password. In this example, it's zsroot.
    2. Enter the following command to configure the ZAB network settings:
    zab configure
    1. Enter the the following information for the network settings:
    1. Enter the following command to verify your configuration:
    zab dump-config

    Zscaler strongly recommends that you change the default password by entering the following command

    passwd <Username>

    For example, if you're using the default username, enter "passwd zsroot".

    Close

  • Install the ZAB SSL certificate you downloaded from the ZIA Admin Portal in 4. Download the ZAB SSL Certificate. The certificate authenticates the ZAB to the Zscaler service.

    To install the ZAB SSL certificate:

    1. Copy the client certificate securely to the ZAB VM. Zscaler recommends that you use SCP or SFTP instead of FTP.
    2. On the ZAB, enter the following command to install the ZAB:
    zab install-client-cert ZabCert.zip

    1. Enter the following command to verify that the ZAB is associated with the Zscaler cloud and your organization:
    zab dump-config

    Close

  • In order for the ZAB to authenticate a user against the AD, it needs to present the user with an authentication form, where the user enters their credentials to be validated against the AD. To be able to serve the form over a webpage, the ZAB has an HTTPS server component running on it.

    You can either install your own certificate signed by a trusted Certificate Authority or install a self-signed certificate. A server certificate from an issuing authority must be used if you're using the ZAB for user authentication. This prevents the user from seeing a server certificate warning in the browser. However, if you're using ZAB only to provision users but not to authenticate them, you can allow the system to generate a self-signed certificate.

    Configure one of the following options:

    • To install a certificate signed by a trusted Certificate Authority:

      1. Copy the server certificate and the private key on to the ZAB.
      2. Copy the full path of the certificate and the private key.
      3. Enter the following command:
      zab install-server-cert
      1. Enter the full path of the server certificate in PEM format.
      2. Enter the full path of the server private key.
      3. (Optional) Enter a passphrase to decrypt the private key. There are no restrictions for the passphrase.
      4. Enter y when it asks if you have a separate host CA certificate file.
      5. Enter the full path of the host CA certificate in PEM format.
      root@ZAB:/usr/home/zsroot/servercerts # zab install-server-cert
Please enter full path of the server certificate in PEM format (Empty to generate self-signed cert): /var/test_servercert.pem
Please enter full path of the server key in PEM format: /usr/home/zsroot/servercerts/zscaler.encrypted.key
Please enter passphrase for decrypting the server key:
REPEAT: Please enter passphrase for decrypting the server key:
Validating pass_phrase with /usr/home/zsroot/servercerts/zscaler.encrypted.key...
Pass phrase works!
Do you have a separate host CA certificate file? <y/n> : [y]: y
Please enter complete path of the host CA certificate file:/usr/home/zsroot/servercerts/chain.pem
Copying files to /sc/conf...
Finished server certificate installation.
      Close

    • To install a self-signed certificate:

      1. Enter the command:
      zab install-server-cert

      1. Click Enter on your keyboard.
      2. Under Self signed certificate generation, enter your domain name.
      3. Enter a passphrase for generating the certificate. There are no restrictions for the passphrase.
      Close
    Close

  • To install and start the ZAB software:

    1. Enter the following command to install and update the ZAB software:
    zab update-now

    1. Enter the following command to start the ZAB:
    zab start

    1. Enter the following command to enable ZAB automatic startup:
    zab enable-autostart

    1. Enter the following command to display the process running:
    zab status

    1. Enter the following command to verify the ZAB is making outbound connections:
    sockstat -4

    Close

  • Nesting groups is adding a group as a member of another group in order to consolidate member accounts and reduce replicated traffic. Enabling nested groups on the ZAB allows the Zscaler service to flatten and sync user group membership for nested groups.

    To enable nested groups on the ZAB:

    1. Enter the following command to enable nested groups:
    zab enable-nested-groups

    1. Restart the ZAB

    To disable nested groups on the ZAB:

    1. Enter the following command to disable nested groups:
    zab disable-nested-groups

    1. Restarts the ZAB
    Close

  • After you configure the ZAB, you must use the Zscaler Authentication Wizard to synchronize users with the ZAB. You optionally can configure the service to use the ZAB for authentication as well. To learn more about the steps in the Authentication Wizard, see Synchronizing User Data with an Active Directory or OpenLDAP.

    To configure the Zscaler service to synchronize users with the ZAB:

    1. In the ZIA Admin Portal, go to Administration > Authentication Settings.
    2. In the Authentication Profile tab, under Directory Type, choose Active Directory.

    1. Click Authentication Wizard.

    1. In Directory Server:
      1. Authentication Agent Hosting: Choose Enterprise.
      2. Directory Server IP Address: Enter the IP address of the directory server that the ZAB connects to.
      3. Authentication Agent Address: Enter the ZAB URL if your organization is using the ZAB for user authentication. If your organization is using another authentication mechanism (e.g., SAML or OpenLDAP), then you can enter any IP address.
      4. Click Next.

    1. In Authentication:
      1. Use Anonymous Authentication: Enable if the directory server allows anonymous access. Ensure that this option is also enabled on your directory server.
      2. Bind DN: Enter the DN of any user account to query the directory server. The user doesn't have to be an administrator.
      3. Bind Password: Enter the password of the entered user account.
      4. Click Next.

    1. In Detected Settings:
      1. Base DN: The Zscaler service connects to the directory server and automatically populates this field.
      2. Pagination: Choose Auto (Recommended).
      3. Click Next.

    1. In Lookup & Attributes:
      1. Lookup Parameters: Choose Auto.
      2. Lookup User Entry: Enter an email address, login name, DN, or LDAP attribute., and click Look Up User. The Zscaler service queries the directory server for the user entry and attributes.
      3. Lookup Results: Displays the user's attributes that were retrieved from the directory server. The Zscaler service uses this information to populate the Attributes Field section below.
      4. Click Next.

    1. In Synchronization, click Start Synchronization to start synchronizing the Zscaler service with the directory server. The wizard displays the synchronization status and results. Click Next.

    1. In Authentication Parameters:
      1. Test User Login: Enter a test user's login ID.
      2. Test User Password: Enter a test user's password.
      3. Check Authentication: Click to verify the user's credentials, and ensure the information was synchronized correctly.
      4. Click Next.

    1. In Review, click Finish.
    Close

  • Optionally, if you have a local NTP server, you can configure the ZAB to synchronize time with the server.

    To configure the ZAB to synchronize time with the NTP server:

    1. On the ZAB, enter the following command:
    crontab -e
    1. Add the following line with your local NTP server name:
    */10 * * * * ntpdate <NTP Server Name>
    1. Save and exit.

    The time synchronization command runs every 10 minutes.

    Close

Troubleshooting

You can use the following commands to troubleshoot your ZAB configuration:

  • Enter the following command to view a ​​list of the ZAB commands:
zab -h
  • Enter the following command to run a script to test access to the outbound firewall:
zab test-firewall
  • Enter the following command to collect all the relevant ZAB log files and configuration files. You can then compress the files into a ZIP file and send it to Zscaler Support for troubleshooting.
zab collect-diagnostics
  • Enter the following command to allow Zscaler Support remote access to examine and diagnose configuration errors. This feature is disabled by default.
zab enable-remote-debugging
  • Enter the following command to allow Zscaler Support remote access to log in to your ZAB via SSH. An interactive shell is useful when additional troubleshooting assistance is required. This feature is disabled by default.
zab support-access-start
Related Articles
About the Zscaler Authentication BridgeDeploying a Zscaler Authentication BridgeAdding a Zscaler Authentication BridgeDownloading the Zscaler Authentication Bridge VMZscaler Authentication Bridge Server Certificate Renewal Process