zscaler.ziacloud.zia_url_filtering_rules module – Adds a new URL Filtering rule.

Note

This module is part of the zscaler.ziacloud collection (version 2.0.3).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install zscaler.ziacloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: zscaler.ziacloud.zia_url_filtering_rules.

New in zscaler.ziacloud 1.0.0

Synopsis

  • Adds a new URL Filtering rule.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

action

string / required

Action taken when traffic matches rule criteria

When the action is set to CAUTION the attribute request_methods accepts only the following values are CONNECT GET HEAD

Choices:

  • "ANY"

  • "BLOCK"

  • "CAUTION"

  • "ALLOW"

  • "ISOLATE"

  • "ICAP_RESPONSE"

api_key

string

A string that contains the obfuscated API key.

block_override

boolean

When set to true, a BLOCK action triggered by the rule could be overridden.

If true and both override_group and override_users are not set, the BLOCK triggered by this rule could be overridden for any users.

If block_override is not set, BLOCK action cannot be overridden.

Choices:

  • false

  • true

cbi_profile

dictionary

The cloud browser isolation profile to which the ISOLATE action is applied in the URL Filtering Policy rules.

This parameter is required for the ISOLATE action and is not applicable to other actions.

id

string / required

The universally unique identifier (UUID) for the browser isolation profile.

name

string / required

Name of the browser isolation profile.

url

string / required

The browser isolation profile URL.

cipa_rule

boolean

If set to true, the CIPA Compliance rule is enabled

Choices:

  • false

  • true

client_id

string

The client ID for OAuth2 authentication.

client_secret

string

The client secret for OAuth2 authentication.

cloud

string

The Zscaler cloud name provisioned for your organization.

Choices:

  • "zscloud"

  • "zscaler"

  • "zscalerone"

  • "zscalertwo"

  • "zscalerthree"

  • "zscalerbeta"

  • "zscalergov"

  • "zscalerten"

  • "beta"

  • "production"

departments

list / elements=integer

Name-ID pairs of departments for which rule will be applied

description

string

Additional information about the rule

device_groups

list / elements=integer

Name-ID pairs of device groups for which the rule must be applied.

This field is applicable for devices that are managed using Zscaler Client Connector.

If no value is set, this field is ignored during the policy evaluation.

device_trust_levels

list / elements=string

List of device trust levels for which the rule must be applied.

This field is applicable for devices that are managed using Zscaler Client Connector.

The trust levels are assigned to the devices based on your posture configurations.

If no value is set, this field is ignored during the policy evaluation.

Choices:

  • "ANY"

  • "UNKNOWN_DEVICETRUSTLEVEL"

  • "LOW_TRUST"

  • "MEDIUM_TRUST"

  • "HIGH_TRUST"

devices

list / elements=integer

Name-ID pairs of devices for which rule must be applied.

Specifies devices that are managed using Zscaler Client Connector.

If no value is set, this field is ignored during the policy evaluation.

enabled

boolean

Determines whether the URL Filtering rule is enabled or disabled

Choices:

  • false

  • true

end_user_notification_url

string

URL of end user notification page to be displayed when the rule is matched.

Not applicable if either override_users or override_groups is specified.

enforce_time_validity

boolean

Enforce a set a validity time period for the URL Filtering rule.

Choices:

  • false

  • true

groups

list / elements=integer

Name-ID pairs of groups for which rule must be applied

id

integer

Unique identifier for the URL Filtering policy rule

labels

list / elements=integer

The URL Filtering rule label. Rule labels allow you to logically group your organization policy rules.

Policy rules that are not associated with a rule label are grouped under the Untagged label.

location_groups

list / elements=integer

Name-ID pairs of the location groups to which the rule must be applied.

locations

list / elements=integer

Name-ID pairs of locations for which rule must be applied

name

string / required

Name of the URL Filtering policy rule

order

integer / required

Rule order number of the URL Filtering policy rule

override_groups

list / elements=integer

Name-ID pairs of groups for which this rule can be overridden.

Applicable only if block_override is set to true and action is BLOCK.

If this override_groups is not set, BLOCK action can be overridden for any group.

override_users

list / elements=integer

Name-ID pairs of users for which this rule can be overridden.

Applicable only if block_override is set to true, action is BLOCK and override_groups is not set.

If this override_users is not set, BLOCK action can be overridden for any user.

password

string

A string that contains the password for the API admin.

private_key

string

The private key for JWT-based OAuth2 authentication.

protocols

list / elements=string / required

Protocol criteria

Choices:

  • "WEBSOCKETSSL_RULE"

  • "WEBSOCKET_RULE"

  • "DOHTTPS_RULE"

  • "TUNNELSSL_RULE"

  • "HTTP_PROXY"

  • "FOHTTP_RULE"

  • "FTP_RULE"

  • "HTTPS_RULE"

  • "HTTP_RULE"

  • "SSL_RULE"

  • "TUNNEL_RULE"

provider

dictionary

A dict containing authentication credentials.

api_key

string

Obfuscated API key.

client_id

string

OAuth2 client ID.

client_secret

string

OAuth2 client secret.

cloud

string

Zscaler cloud name.

Choices:

  • "zscloud"

  • "zscaler"

  • "zscalerone"

  • "zscalertwo"

  • "zscalerthree"

  • "zscalerbeta"

  • "zscalergov"

  • "zscalerten"

  • "beta"

  • "production"

password

string

Password for the API admin.

private_key

string

Private key for OAuth2 JWT.

sandbox_cloud

string

Sandbox Cloud environment.

sandbox_token

string

Sandbox API Key.

use_legacy_client

boolean

Whether to use the legacy Zscaler API client.

Choices:

  • false ← (default)

  • true

username

string

Email ID of the API admin.

vanity_domain

string

Vanity domain for OAuth2.

rank

integer

Admin rank of the admin who creates this rule

Default: 7

request_methods

list / elements=string

Request method for which the rule must be applied.

If not set, rule will be applied to all methods”

Choices:

  • "OPTIONS"

  • "GET"

  • "HEAD"

  • "POST"

  • "PUT"

  • "DELETE"

  • "TRACE"

  • "CONNECT"

  • "OTHER"

  • "PROPFIND"

  • "PROPPATCH"

  • "MOVE"

  • "MKCOL"

  • "LOCK"

  • "COPY"

  • "UNLOCK"

  • "PATCH"

sandbox_cloud

string

The Sandbox cloud environment for API access.

sandbox_token

string

A string that contains the Sandbox API Key.

size_quota

integer

Action must be set to CAUTION

Size quota in MB beyond which the URL Filtering rule is applied.

The allowed range is between 10 MB and 100000 MB

If not set, no quota is enforced. If a policy rule action is set to BLOCK, this field is not applicable.

source_ip_groups

list / elements=integer

User-defined source IP address groups for which the rule is applicable.

If not set, the rule is not restricted to a specific source IP address group.

state

string

Specifies the desired state of the resource.

Choices:

  • "present" ← (default)

  • "absent"

time_quota

integer

Action must be set to CAUTION

Time quota in minutes, after which the URL Filtering rule is applied.

The allowed range is between 15 minutes and 600 minutes.

If not set, no quota is enforced. If a policy rule action is set to BLOCK, this field is not applicable.

time_windows

list / elements=integer

Name-ID pairs of time interval during which rule must be enforced.

url_categories

list / elements=string

The URL categories to which the rule applies

Use the info resource zia_url_categories_info to retrieve the category names.

use_legacy_client

boolean

Whether to use the legacy Zscaler API client.

Choices:

  • false ← (default)

  • true

user_agent_types

list / elements=string

Any number of user agents to which the rule applies.

Choices:

  • "OPERA"

  • "FIREFOX"

  • "MSIE"

  • "MSEDGE"

  • "CHROME"

  • "SAFARI"

  • "OTHER"

  • "MSCHREDGE"

user_risk_score_levels

list / elements=string

Indicates the user risk level selected for the DLP rule violation.

Choices:

  • "LOW"

  • "MEDIUM"

  • "HIGH"

  • "CRITICAL"

username

string

A string that contains the email ID of the API admin.

users

list / elements=integer

Name-ID pairs of users for which rule must be applied

validity_end_time

string

If enforce_time_validity is set to true, the URL Filtering rule will cease to be valid on this end date and time.

Example ( 12/21/2023 12:00 AM )

validity_start_time

string

If enforce_time_validity is set to true, the URL Filtering rule will be valid starting on this date and time.

Example ( 11/20/2023 11:59 PM )

Notice that validity_start_time cannot be in the past

validity_time_zone_id

string

If enforceTimeValidity is set to true, the URL Filtering rule date and time is valid based on this time zone ID.

vanity_domain

string

The vanity domain provisioned by Zscaler for OAuth2 flows.

workload_groups

list / elements=integer

The list of preconfigured workload groups to which the policy must be applied.

Notes

Note

  • Check mode is supported.

Examples

- name: Create/Update/Delete a URL Filtering Rule.
  zscaler.ziacloud.zia_url_filtering_rules:
    provider: '{{ provider }}'
    name: "URL_Ansible_Example"
    description: "URL_Ansible_Example"
    enabled: "ENABLED"
    action: "ALLOW"
    order: 1
    source_ip_groups:
      - 4361664
      - 4522587
    protocols:
      - "HTTPS_RULE"
      - "HTTP_RULE"
    request_methods:
      - "CONNECT"
      - "DELETE"
      - "GET"
      - "HEAD"
      - "OPTIONS"
      - "OTHER"
      - "POST"
      - "PUT"
      - "TRACE"

Authors

  • William Guilherme (@willguibr)