-> Disclaimer: Please refer to our General Support Statement before proceeding with the use of this collection. You can also refer to our troubleshooting guide for guidance on typical problems.

This collection contains modules and plugins to assist in automating the configuration and operational tasks on Zscaler Internet Access cloud, and API interactions with Ansible.

• Free software: MIT License
• Documentation
• Repository
• Example Playbooks

This collection is tested with the most current Ansible releases. Ansible versions before 2.15 are not supported.

The minimum python version for this collection is python 3.9.

The Python module dependencies are not automatically handled by ansible-galaxy. To manually install these dependencies, you have the following options:

1. Utilize the requirements.txt file located here to install all required packages:

  pip install -r requirements.txt

2. Alternatively, install the Zscaler SDK Python package directly:

  pip install zscaler-sdk-python

Install this collection using the Ansible Galaxy CLI:

ansible-galaxy collection install zscaler.ziacloud

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:

  collections:
    - zscaler.ziacloud

The ZIA Ansible Collection now offers support for OneAPI OAuth2 authentication through Zidentity.

NOTE As of version v2.0.0, this Ansible Collection offers backwards compatibility to the Zscaler legacy API framework. This is the recommended authentication method for organizations whose tenants are still not migrated to Zidentity.

NOTE Notice that OneAPI and Zidentity is not currently supported for the following clouds: zscalergov and zscalerten. Refer to the Legacy API Framework for more information on how authenticate to these environments

It's preferable to use content in this collection using their Fully Qualified Collection Namespace (FQCN), for example zscaler.ziacloud.zia_cloud_firewall_rule:

---
- name: ZIA Cloud Firewall Rule
  hosts: localhost

  vars:
    zia_cloud:
      client_id: "{{ lookup('env', 'ZSCALER_CLIENT_ID') }}"
      client_secret: "{{ lookup('env', 'ZSCALER_CLIENT_SECRET') }}"
      vanity_domain: "{{ lookup('env', 'ZSCALER_VANITY_DOMAIN') }}"
      cloud: "{{ lookup('env', 'ZSCALER_CLOUD') | default(omit) }}"

  tasks:
    - name: Create/update firewall rule
      zscaler.ziacloud.zia_cloud_firewall_rule:
        provider: "{{ zia_cloud }}"
        name: "Ansible Example"
        description: "Ansible Example"
        action: "ALLOW"
        rule_state: "ENABLED"
        order: 1
        enable_full_logging: true
        nw_services:
          - "774003"
          - "774013"
      register: created_rule
    - debug:
        msg: "{{ created_rule }}"

(Note that use of the collections key is now discouraged)

NOTE: The zscaler_cloud is optional and only required when authenticating to other environments i.e beta

⚠️ WARNING: Hard-coding credentials into any Ansible playbook configuration is not recommended, and risks secret leakage should this file be committed to public version controls.

---
- name: ZIA Cloud Firewall Rule
  hosts: localhost

  vars:
    zia_cloud:
      client_id: "{{ client_id | default(omit) }}"
      private_key: "{{ lookup('file', 'private_key.pem') | default(omit) }}"
      vanity_domain: "{{ vanity_domain | default(omit) }}"
      cloud: "{{ cloud | default(omit) }}"

  tasks:
    - name: Create/update firewall rule
      zscaler.ziacloud.zia_cloud_firewall_rule:
        provider: "{{ zia_cloud }}"
        name: "Ansible Example"
        description: "Ansible Example"
        action: "ALLOW"
        rule_state: "ENABLED"
        order: 1
        enable_full_logging: true
        nw_services:
          - "774003"
          - "774013"
      register: created_rule
    - debug:
        msg: "{{ created_rule }}"

As of version v2.0.0, this provider supports authentication via the new Zscaler API framework OneAPI

Zscaler OneAPI uses the OAuth 2.0 authorization framework to provide secure access to Zscaler Internet Access (ZIA) APIs. OAuth 2.0 allows third-party applications to obtain controlled access to protected resources using access tokens. OneAPI uses the Client Credentials OAuth flow, in which client applications can exchange their credentials with the authorization server for an access token and obtain access to the API resources, without any user authentication involved in the process.

• ZIA API

You can provide credentials via the ZSCALER_CLIENT_ID, ZSCALER_CLIENT_SECRET, ZSCALER_VANITY_DOMAIN, ZSCALER_CLOUD environment variables, representing your Zidentity OneAPI credentials clientId, clientSecret, vanityDomain and zscaler_cloud respectively.

OneAPI supports authentication and can interact with alternative Zscaler enviornments i.e beta. To authenticate to these environments you must provide the following values:

For example: Authenticating to Zscaler Beta environment:

export ZSCALER_VANITY_DOMAIN="acme"
export ZSCALER_CLOUD="beta"

OneAPI Resources are automatically created within the ZIdentity Admin UI based on the RBAC Roles applicable to APIs within the various products. For example, in ZIA, navigate to Administration -> Role Management and select Add API Role.

Once this role has been saved, return to the ZIdentity Admin UI and from the Integration menu select API Resources. Click the View icon to the right of Zscaler APIs and under the ZIA dropdown you will see the newly created Role. In the event a newly created role is not seen in the ZIdentity Admin UI a Sync Now button is provided in the API Resources menu which will initiate an on-demand sync of newly created roles.

• As of version v2.0.0, this Ansible Collection offers backwards compatibility to the Zscaler legacy API framework. This is the recommended authentication method for organizations whose tenants are still NOT migrated to Zidentity.

---
- name: ZIA Cloud Firewall Rule
  hosts: localhost

  vars:
    zia_cloud:
      username: "{{ username | default(omit) }}"
      password: "{{ password | default(omit) }}"
      api_key: "{{ api_key | default(omit) }}"
      cloud: "{{ cloud | default(omit) }}"
      use_legacy_client: "{{ use_legacy_client | default(omit) }}"

  tasks:
    - name: Create/update firewall rule
      zscaler.ziacloud.zia_cloud_firewall_rule:
        provider: "{{ zia_cloud }}"
        name: "Ansible Example"
        description: "Ansible Example"
        action: "ALLOW"
        rule_state: "ENABLED"
        order: 1
        enable_full_logging: true
        nw_services:
          - "774003"
          - "774013"
      register: created_rule
    - debug:
        msg: "{{ created_rule }}"

The ZIA Cloud is identified by several cloud name prefixes, which determines which API endpoint the requests should be sent to. The following cloud environments are supported:

• zscaler
• zscloud
• zscalerone
• zscalertwo
• zscalerthree
• zscalerbeta
• zscalergov
• zscalerten
• zspreview

You can provide credentials via the ZIA_USERNAME, ZIA_PASSWORD, ZIA_API_KEY, ZIA_CLOUD, ZSCALER_USE_LEGACY_CLIENT environment variables, representing your ZIA username, password, api_key, zia_cloud and use_legacy_client respectively.

# Change place holder values denoted by brackets to real values, including the
# brackets.

$ export ZIA_USERNAME="[ZIA_USERNAME]"
$ export ZIA_PASSWORD="[ZIA_PASSWORD]"
$ export ZIA_API_KEY="[ZIA_API_KEY]"
$ export ZIA_CLOUD="[ZIA_CLOUD]"
$ export ZSCALER_USE_LEGACY_CLIENT=true

⚠️ WARNING: Hard-coding credentials into any Ansible playbook configuration is not recommended, and risks secret leakage should this file be committed to public version control

For details about how to retrieve your tenant Base URL and API key/token refer to the Zscaler help portal. https://help.zscaler.com/zia/getting-started-zia-api

As of version v2.0.0, the legacy sandbox authentication environment variables ZIA_CLOUD and ZIA_SANDBOX_TOKEN are no longer supported.

Authentication to the Zscaler Sandbox service requires the following new environment variables the ZSCALER_SANDBOX_CLOUD and ZSCALER_SANDBOX_TOKEN or authentication attributes sandbox_token and sandbox_cloud. For details on how obtain the API Token visit the Zscaler help portal About Sandbox API Token

The intended release frequency for major and minor versions are performed whenever there is a need for fixing issues or to address security concerns.

Changelog details are created automatically and more recently can be found here, but also the full history is here.

Semantic versioning is adhered to for this project.

Deprecations are done by version number, not by date or by age of release. Breaking change deprecations will only be made with major versions.

The Zscaler Internet Access (ZIA) Collection of Ansible Modules is certified on Ansible Automation Hub and officially supported for Ansible subscribers. Ansible subscribers can engage for support through their usual route towards Red Hat.

For those who are not Ansible subscribers, this Collection of Ansible Modules is also published on Ansible Galaxy and also supported via the formal Zscaler suppport process. Please refer to our General Support Statement

Copyright (c) 2023 Zscaler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.