To connect your Zscaler tenant to Commvault, you must configure a credential with the required permissions and provide the authentication details Commvault needs to connect.
Create or identify a Zscaler credential
Create an active Zscaler OneAPI client in your Zscaler admin portal. This client provides OAuth 2.0 credentials (client ID and client secret) and allows you to assign the required ZIA and ZPA API resources and roles.
To create the OneAPI client:
-
Sign in to the Zscaler admin portal.
-
Go to Administration > API Key Management or the OneAPI client configuration section.
-
Create a new OneAPI client or select an existing one.
-
Note the Client ID.
-
Generate or retrieve the Client Secret.
-
Note your Vanity Domain (tenant prefix only, for example
commvaultengineering; do not include a URL, protocol, or domain suffix). -
For ZPA protection, note your Customer ID (supplied to the OneAPI client as
customerId).
Assign the required permissions
Assign the following API resources and roles to the Zscaler OneAPI client to enable backup and restore operations. The role must be permitted to list and modify every configuration category selected for protection.
| Operation | Required role/API resource | What it grants |
|---|---|---|
| Browse ZIA categories | ZIA API role with list permission | Read access to ZIA configuration objects |
| Backup ZIA configuration | ZIA API role with read permission | Read access to Rule Labels, DLP Dictionaries, DLP Engines, URL Filter Rules, Firewall Rules, SSL Inspection Rules, Bandwidth Control Rules, Locations, Cloud App Control Rules, Authentication Settings |
| Restore ZIA configuration | ZIA API role with create/update permission | Write access to create or update ZIA configuration objects |
| Activate ZIA changes | ZIA API role with activation permission | Permission to activate pending configuration changes in ZIA |
| Browse ZPA categories | ZPA API role with list permission | Read access to ZPA configuration objects |
| Backup ZPA configuration | ZPA API role with read permission | Read access to Segment Groups, Application Segments, App Connector Groups, Trusted Networks, PRA Consoles, PRA Portals, Policies |
| Restore ZPA configuration | ZPA API role with create/update permission | Write access to create or update ZPA configuration objects |
Before assigning the ZIA role to the OneAPI client, synchronize it in Zidentity API Resources. This ensures the role is properly recognized by the Zscaler authentication system.
Provide connection details
When configuring protection in Commvault, you provide the following connection details:
-
Username: The OneAPI client ID (found in the Zscaler admin portal under API Key Management).
-
Password: The OneAPI client secret (generated when the OneAPI client was created or refreshed).
-
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 as
customerId(found in the Zscaler admin portal).
Notes and considerations
OAuth tokens expire based on the configured lifetime in the Zscaler OneAPI client settings. Commvault automatically refreshes tokens using the client credentials as long as the client remains active and not revoked.
Use a dedicated service account for Commvault integrations rather than a personal user account. This avoids disruption if individual user access changes or accounts are disabled.
Ensure that client access policies in Zscaler permit the Commvault MediaAgent or worker network source. Blocked network sources prevent API access even with valid credentials.
Validate permissions
Run a test backup after configuring credentials to confirm that permissions are correctly assigned.
If the backup fails with an authentication error such as "Invalid credentials" or "Unauthorized," check the following:
-
Verify that the client ID and client secret are correct.
-
Confirm that the vanity domain is entered as a tenant prefix only, without URL or protocol.
-
Ensure that the OneAPI client is active and not disabled or revoked in the Zscaler admin portal.
-
For ZPA protection, verify that the customer ID is correct.
If the backup fails with a permissions error such as "Insufficient privileges" or "Access denied," verify the following:
-
The ZIA role has list and read permissions for all selected ZIA categories.
-
The ZPA role has list and read permissions for all selected ZPA categories.
-
The ZIA role has been synchronized in Zidentity API Resources before assignment to the OneAPI client.
-
The OneAPI client has been assigned the required API resources and roles.
If a restore fails with an activation error, verify that the ZIA role has activation permission granted. ZIA changes cannot take effect without successful activation.