Configure and validate backups for Zscaler

Set up and validate backups for Zscaler.

Onboard Zscaler

Onboard a Zscaler tenant to begin protecting your Zscaler configuration data. During onboarding, you connect to Zscaler, choose the content to protect, assign a backup plan, and create the backup configuration.

Start the configuration

1. From the Command Center navigation pane, go to Protect > SaaS Apps.

2. Click Add SaaS Application.

3. Select Zscaler, and then click Next.

Specify credentials

Cloud App Connection Details

• In the Name field, provide a display name for this Zscaler backup configuration.

Configure Credential

• Username: The OneAPI client ID from your Zscaler admin portal.

• Password: The OneAPI client secret.

• Vanity Domain: The tenant prefix only (for example, commvaultengineering). Do not include a URL, protocol, or domain suffix.

• Customer ID (required for ZPA): The ZPA customer ID supplied to the OneAPI client.

Choose the backup content

• Click the pencil (edit) icon next to Content.

• Choose either: select the ZIA and ZPA categories shown in the browse tree, or define rules to select content for the subclient.

The browse tree displays the Zscaler tenant as the top-level object with ZIA and ZPA as the two main branches. Expand each branch to view supported configuration categories. Only categories verified as backup-and-restore capable appear in the browse tree.

Select a backup plan

• Select an existing backup plan, or click + to create a new one.

• After you create a backup plan, you can select it when you onboard additional Zscaler tenants.

Review summary

• Review the instance name, plan name, schedule, and backup content.

• Click Submit.

Run a backup

1. From the Command Center navigation pane, go to Protect > SaaS Apps.

2. For the application that you want to back up, click the action button, and then click Back up now to run a Full backup.

3. Monitor job progress in the Jobs view.

Zscaler tenant and API rate limits apply. The workload does not impose a fixed request-per-second rate, so large tenants or configurations with many objects per category might take longer to back up. Schedule large tenants conservatively and investigate Zscaler 429 throttling responses if they occur.

Validate the backup

Verify the configuration

After you assign the backup plan, confirm that:

• The Zscaler configuration appears in the SaaS Apps list with the display name you provided.

• The Zscaler tenant appears in the browse tree under the configuration.

• Supported ZIA and ZPA categories are visible when you expand the tenant in the browse tree.

Confirm that the backup completed successfully

1. From the Command Center navigation pane, go to Monitor > Jobs.

2. Locate the completed backup job.

3. Verify that the job status is Completed.

4. Check the job details to confirm:

   • The number of categories backed up matches the expected count for your selected configuration.

   • The backup duration is reasonable for the configuration size and object count.

   • The storage size reflects the total size of configuration JSON documents.

Test a restore

1. From the Jobs view, select the completed backup job.

2. Click Restore.

3. Select one or more ZIA or ZPA categories to restore.

4. In the Restore Destination section, select the original Zscaler instance for in-place restore, or select a separately configured destination instance for out-of-place restore.

5. Click Submit.

6. Verify that the restore completes with status Completed and that the configuration matches the original.

For complete restore procedures, see Restore Zscaler data.

Common causes of failures and what to check first

Configuration and permissions failures

• Authentication failures: "Invalid credentials" or "Unauthorized" errors indicate that the client ID, client secret, vanity domain, or customer ID is incorrect. Verify that the credentials match the OneAPI client configuration in the Zscaler admin portal.

• Missing permissions: "Insufficient privileges" or "Access denied" errors indicate that the OneAPI client does not have the required API resources and roles. Confirm that ZIA and ZPA roles have list and read permissions for all selected categories.

• Role synchronization: If ZIA API calls fail after assigning roles, verify that the ZIA role was synchronized in Zidentity API Resources before assignment to the OneAPI client.

• Revoked client: If the OneAPI client is disabled or revoked in the Zscaler admin portal, all API calls will fail. Check the client status and reactivate it if necessary.

Backup job failures

• Rate limit exceeded: Backups might slow or pause when Zscaler tenant or API rate limits are reached. The SDK and Zscaler service determine retry behavior. If backups consistently hit rate limits, schedule them during off-peak hours or reduce the number of categories backed up in a single job.

• Category read failure: If a selected supported category fails to read, the backup job fails rather than silently proceeding. Review the job log to identify the failing category and verify API permissions and tenant configuration.

• Network connectivity: If the access node cannot reach the Zscaler API endpoint, check firewall rules, IP allowlisting, and DNS resolution for the Zscaler endpoint. Verify that client access policies permit the Commvault MediaAgent or worker network source.

Restore failures

• Activation failure: After successful ZIA writes, Commvault automatically invokes ZIA activation. If activation fails, the restore job fails because changes would otherwise remain pending. Verify that the ZIA role has activation permission granted.

• Missing destination credentials: Out-of-place restore requires a separately configured destination Zscaler instance with valid OneAPI credentials. Ensure the destination instance is created and configured in Commvault before starting an out-of-place restore.

• Tenant-specific authorization: Per-object Zscaler authorization, tenant hierarchy, and feature licensing can still reject an otherwise supported update. These are returned as restore errors for specific objects, not as a failed job. Review the job log for per-category restored, skipped, and errors counts.

• Unsupported category restore: If a restore selection originates from an older backup that contains unsupported categories (such as ZIA Admin Roles or ZPA Server Groups), those tasks are logged and completed as intentional skips. Verify that the selected categories are in the current supported hierarchy.