はじめに
こんにちは、エーピーコミュニケーションズiTOC事業部BzD部、0-WAN所属の齋藤です。
Zscalerの各サービスでは様々な方法でAPIを実行することができます。
今回はZscaler公式のAnsibleコレクションである「zscaler.ziacloud」を利用して、ZIAのカスタムURLカテゴリ及びURLフィルタリングポリシーを作成するデモを行いましたので、その手順をご紹介します。
1. zscaler.ziacloudとは
zscaler.ziacloudはZscaler社が開発・提供する、ZIAの設定・運用自動化をサポートするRed Hat Ansible認定コンテンツとしてAnsible Galaxyで公開されています。
またZPA用のzscaler.zpacloudも提供されており、現在はこれら2種類のAnsibleコレクションが利用可能です。
2. OneAPIと認証方式について
具体的なデモの内容に移る前に、OneAPIと採用したAPIクライアントの認証方式について説明します。
OneAPI
ZIA、ZPA、ZCCといった各サービスごとにAPIキーを管理しなければならなかったレガシーAPIと異なり、OneAPIは1つのAPIクライアントでZscalerの様々なサービスへアクセスが可能です。
そんなOneAPIには3つの認証方式が用意されています。
① JWTs方式
② 証明書方式
③ クライアントシークレット方式
今回は実装の容易さと運用のシンプルさを重視して、③のクライアントシークレット方式（以後シークレット方式）を選択しました。
シークレット方式
シークレット方式は、APIクライアントの「クライアントID」と「クライアントシークレット」を検証し、短期間だけ有効なアクセストークンを発行する仕組みです。
大元の鍵である「シークレット」は使わず、使い捨てのトークンを用いて設定変更を行います。
3. 事前準備
ZscalerのOneAPIを使用するためには次の3つの準備が必要です。
①APIサブスクリプション
サブスクリプション契約が必要となります。お使いのテナントでサブスクリプションが有効であるかどうか確認してください。
- Experience Centerでは、Administration > Account Management > Company Profile > Subscriptionsと辿り確認します。
②APIクライアント専用Roleの作成
APIクライアントに割り当てるアクセス権限を定義した、専用のRoleを作成します。
- Administration > Admin Management > Role Based Access Control > Internet & Access > Add API Roleをクリック
- Roleの名前を入力したら、必要な権限を設定していきます。今回のデモではURL Filtering PolicyとURL CategoriesのみFull、他はすべてView Onlyとしました。
③APIクライアントの作成
API専用のクライアントを作成します。
- Administration > API Configuration > OneAPI > API Clients > Add API Clientをクリック
Clientタブを開き、各種設定項目を入力します。
・Name
・Description
・Status
・Access Token Validity (アクセストークンの有効期間です。最小1分、最大1440分です。)
・Client ID (自動生成されます。アクセストークンの発行に使うのでコピーします。)CLIENT AUTHENTICATIONのValidation TypeでSecretを選択します。
※初回のみクライアントシークレットが可視化＆コピーが可能です。セーブすると二度と表示されないのでコピーします。
Resourcesタブを開き、Scopesの中のZIAを展開、作成したAPI用Roleを選択して保存します。
以上で準備は完了です。
4. デモ環境
今回は私のWindows端末にWSLをインストールして、デモ用の仮想環境を構築しました。
#WSLをインストール wsl --install wsl --install -d Ubuntu #開発用のフォルダを作成 mkdir zscaler-ansible #仮想環境を作成する sudo apt install python3-full -y python3 -m venv myvenv #AnsibleとZIA公式プラグインをインストール pip3 install zscaler-sdk-python pip3 install ansible ansible-galaxy collection install zscaler.ziacloud
📂zscaler-ansible/
├── 📂myvenv/
|
├── 📂secret_info/
│ └── user_secret.yml
|
└── 📂playbook/
├── demo_change_config.yaml
├── demo_activation.yaml
├── run_demo.sh
└── 📂params/
├── demo_url_category_params.yml
└── demo_url_filtering_params.yml
5. playbookと各種ファイル
demo_change_config.yaml
カスタムURLカテゴリとURLフィルタリングポリシーを作成するplaybookです。
- name: ZIA Automation Demo hosts: localhost gather_facts: false vars_files: # 認証情報 - "{{ lookup('env', 'ZSCALER_API_SECRET') }}" # 運用者が編集するパラメータ - "{{ url_cat_params | default('./params/demo_url_category_params.yml') }}" - "{{ url_rule_params | default('./params/demo_url_filtering_params.yml') }}" tasks: # ================================================================= # カスタムURLカテゴリの作成 # ================================================================= - name: (Step1) Create custom URL categories zscaler.ziacloud.zia_url_categories: provider: client_id: "{{ client_id }}" client_secret: "{{ client_secret }}" vanity_domain: "{{ vanity_domain }}" configured_name: "{{ Name }}" description: "{{ Description }}" super_category: "{{ URL_Super_Category }}" custom_category: "{{ Custom_category }}" urls: "{{ Custom_URLs }}" state: "present" register: categories_info # ================================================================= # 設定済みのURLフィルタリングポリシーの情報を取得 # ================================================================= - name: (Step2) Get all current URL filtering rules zscaler.ziacloud.zia_url_filtering_rule_info: provider: client_id: "{{ client_id }}" client_secret: "{{ client_secret }}" vanity_domain: "{{ vanity_domain }}" register: current_rules # ================================================================= # URLフィルタリングポリシーの作成 # ================================================================= - name: (Step3) Create URL filtering rules zscaler.ziacloud.zia_url_filtering_rules: provider: client_id: "{{ client_id }}" client_secret: "{{ client_secret }}" vanity_domain: "{{ vanity_domain }}" name: "{{ Rule_Name }}" order: "{{ current_rules.rules | length + 1 }}" #ポリシーを最後尾に置きたい場合の処理、current_rulesの総数+1 enabled: "{{ Rule_Status }}" description: "{{ Description }}" protocols: "{{ Protocols }}" action: "{{ Action }}" url_categories: - "{{ categories_info.data.id }}" #カテゴリ属性がUser Definedの場合は、対象URLカテゴリのIDを指定する
demo_activation.yaml
Activateして設定変更を確定させるplaybookです。
- name: Activate config changes hosts: localhost gather_facts: false vars_files: - "{{ lookup('env', 'ZSCALER_API_SECRET') }}" tasks: - name: Activate zscaler.ziacloud.zia_activation_status: provider: client_id: "{{ client_id }}" client_secret: "{{ client_secret }}" vanity_domain: "{{ vanity_domain }}" status: "ACTIVE"
user_secret.yml
クライアントID、クライアントシークレット、テナントドメインを定義したファイルです。 今回はファイルを暗号化して、環境変数"ZSCALER_API_SECRET"に格納しました。
vanity_domain: "テナントドメイン" client_id: "クライアントID" client_secret: "クライアントシークレット"
demo_url_category_params.yml
カスタムURLカテゴリを作成するためのパラメータを定義したファイルです。
# URLカテゴリ用のパラメータ Name: "API-Demo-UR-Category" URL_Super_Category: "USER_DEFINED" Custom_category: "true" Custom_URLs: - "www.example.com1" - "www.example.com2" - ".example.com" Description: "Demo url categories with API"
demo_url_filtering_params.yml
URLフィルタリングポリシーを作成するためのパラメータを定義したファイルです。
#URLフィルタリングポリシー用のパラメータ Rule_Name: "API-Demo-URL-Filter-Rule" Rule_Status: true Request_Methods: Protocols: - "HTTP_RULE" - "HTTPS_RULE" Action: "ALLOW" Description: "Demo url filtering rules with API"
run_demo.sh
playbookを一括で実行するためのシェルです。
ansible-playbook demo_change_config.yaml --ask-vault-pass read -p "Press Enter if you want to activate." ansible-playbook demo_activation.yaml --ask-vault-pass echo "Activation was completed: "
6. 実行結果
playbookの実行結果です。
Experience Centerの画面上でも想定したURLカテゴリとURLフィルタリングポリシーが作成されていることが確認できました。
7. 感想
zscaler.ziacloudを使ってみた感想を共有したいと思います。
メリット1
最初の利点は、公式ドキュメント（Ansible Galaxyのコレクションドキュメント）の網羅性の高さです。実はAnsibleを触るのが初めてだったのですが、 各モジュールの引数や設定例が詳細に書かれているため、実装難易度が低いと感じました。 「ドキュメント通りに書けば、狙い通りの設定変更が難なくできる」という安心感は、自動化を進める上で大きなメリットです。
メリット2
一からAPIスクリプトを組む場合、リクエストの構造を考えてコードを書く必要がありますが、Ansibleならその必要はありません。 すでに用意されているモジュールに対して、「必要なパラメータを追加・変更するだけ」で設定が完結します。コードの可読性も高く、Ansibleに詳しくない運用メンバーでもメンテナンスがしやすいため、チーム全体の運用難易度をグッと下げてくれると感じました。
注意点1
Pythonなどで独自にAPI連携を実装する場合、最初に1回アクセストークンを発行し、それをAPIリクエスト文に組み込むのが一般的です。 しかしAnsibleコレクションの仕様上、タスク（処理）が実行されるたびにアクセストークンを発行しにいってしまいます。 Experience Centerでは発行済みのアクセストークンを確認できるのですが、私のデモで発行されたトークンだらけになってしまいました。 そのためタスクのまとめ方や実行頻度には少し工夫が必要です。
注意点2
2026年現在、提供されているZscalerの公式AnsibleコレクションはZIAとZPAのみとなっています。
そのため、ZCC（Zscaler Client Connector）や、ZDX（Zscaler Digital Experience）の自動化には、現状このコレクションは使えません。
これらを自動化したい場合は、これまで通り直接APIを叩くスクリプトを自作するなどのアプローチが必要です。今後のコレクションのアップデートに期待です！
0-WANについて
私たち0-WANは、ゼロトラスト製品を中心とした、マルチベンダーでのご提案で、お客様の経営課題解決を支援しております。 ゼロトラストってどうやるの？製品を導入したけれど使いこなせていない気がする等々、どんな内容でも支援いたします。 お気軽にご相談ください。
問い合わせ先、0-WANについてはこちら。
