user_management

The following methods allow for interaction with the ZIA Users, Groups, and Departments API endpoints.

Methods are accessible via zia.user_management

Copyright (c) 2023, Zscaler Inc.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class UserManagementAPI

Bases: APIClient

A Client object for the User Management API resource.

add_department(**kwargs)

Creates a new ZIA Department.

Parameters:

label (dict or object) – The label data to be sent in the request.

Returns:

A tuple containing the newly added Department, response, and error.

Return type:

tuple

add_group(**kwargs)

Creates a new ZIA Group.

Parameters:

label (dict or object) – The label data to be sent in the request.

Returns:

A tuple containing the newly added Group, response, and error.

Return type:

tuple

add_user(**kwargs)

Creates a new ZIA user.

Parameters:

  • name (str) – User name.

  • email (str) – User email consists of a user name and domain name. It does not have to be a valid email address, but it must be unique and its domain must belong to the organisation.

  • groups (list) – List of Groups a user belongs to.

  • department (dict) – The department the user belongs to.

Keyword Arguments:

  • **comments (str) – Additional information about this user.

  • **tempAuthEmail (str) – Temporary Authentication Email. If you enabled one-time tokens or links, enter the email address to which the Zscaler service sends the tokens or links. If this is empty, the service will send the email to the User email.

  • **adminUser (bool) – True if this user is an Admin user.

  • **password (str) – User’s password. Applicable only when authentication type is Hosted DB. Password strength must follow what is defined in the auth settings.

  • **type (str) – User type. Provided only if this user is not an end user. Accepted values are SUPERADMIN, ADMIN, AUDITOR, GUEST, REPORT_USER and UNAUTH_TRAFFIC_DEFAULT.

Returns:

The resource record for the new user.

Return type:

Tuple

Examples

Add a user with the minimum required params:

>>> user, _, err = zia.users.add_user(name='Jane Doe',
...    email='jane.doe@example.com',
...    groups=[{
...      'id': '49916183'}]
...    department={
...      'id': '49814321'})
bulk_delete_users(user_ids)

Bulk delete ZIA users.

Parameters:

user_ids (list) – List containing id int of each user that will be deleted.

Returns:

Object containing list of users that were deleted.

Return type:

Tuple

Examples

>>> bulk_delete_users = zia.users.bulk_delete_users(['99999', '88888', '77777'])
delete_department(deparment_id)

Deletes the specified Department.

Parameters:

deparment_id (str) – The unique identifier of the Department.

Returns:

A tuple containing the response object and error (if any).

Return type:

tuple

Example

Delete department:

>>> _, _, error = client.zia.user_management.delete_department('554458')
... if error:
...     print(f"Error deleting department: {error}")
...     return
delete_group(group_id)

Deletes the specified Group.

Parameters:

group_id (str) – The unique identifier of the Group.

Returns:

A tuple containing the response object and error (if any).

Return type:

tuple

delete_user(user_id)

Deletes the specified user ID.

Parameters:

user_id (str) – The unique identifier of the user that will be deleted.

Returns:

The response code for the request.

Return type:

int

Examples

>>> user = zia.users.delete_user('99999')
get_department(department_id)

Returns information on the specified department id.

Parameters:

department_id (str) – The unique identifier for the department.

Returns:

A tuple containing (UserManagement instance, Response, error)

Return type:

tuple

Examples

>>> department = zia.users.get_department('99999')
get_department_lite(department_id)

Returns information on the specified department id.

Parameters:

department_id (str) – The unique identifier for the department.

Returns:

A tuple containing (Department instance, Response, error)

Return type:

tuple

Examples

>>> department = zia.users.get_department('99999')
get_group(group_id)

Returns the user group details for a given user group.

Parameters:

group_id (str) – The unique identifier for the user group.

Returns:

The user group resource record.

Return type:

Tuple

Examples

>>> fetched_department, _, error = client.zia.user_management.get_group('545225')
... if error:
...     print(f"Error fetching department by ID: {error}")
...     return
... print(f"Fetched department by ID: {fetched_department.as_dict()}")
get_group_lite(query_params=None)

Returns the user group ID and Name.

Parameters:

query_params (dict, optional) –

Map of query parameters for the request.

  • limit_search (bool, optional): Limits the search to match against the department name only

  • search (str, optional): Search string used to match against an admin/auditor user’s Login ID or Name

  • page (int, optional): Specifies the page offset.

  • page_size (int, optional): Specifies the page size.

    The default size is 100, but the maximum size is 1000.

  • sort_by (str, optional): Sorts the departments based on available values.

    Supported Values: id, name, expiry, status, external_id, rank

  • sort_order (str, optional): Sorts the order of departments based on available values.

    Supported Values: asc, desc, rule_execution

Returns:

The user group resource record.

Return type:

tuple

Examples

>>> user_group = zia.users.get_group('99999')
get_user(user_id)

Returns the user information for the specified ID or email.

Parameters:

user_id (optional, str) – The unique identifier for the requested user.

Returns:

The resource record for the requested user.

Return type:

Tuple

Examples
>>> user, _, error = client.zia.user_management.get_group(updated_group.id)
... if error:
...     print(f"Error fetching group by ID: {error}")
...     return
... print(f"Fetched group by ID: {fetched_group.as_dict()}")
list_auditors(query_params=None)

Returns the list of auditor users.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.dept] {str}: Filters by department name. This is a starts with match. [query_params.group] {str}: Filters by group name. This is a starts with match. [query_params.name] {str}: Filters by user name. This is a starts with match. [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Specifies the page size.

The default size is 100, but the maximum size is 1000.

Returns:

A tuple containing (list of UserManagement instances, Response, error)

Return type:

tuple

Example

List all auditor users:

>>> user_list, response, error = zia.user_management.list_rules(
...    query_params={'page': 1, "page_size": 10}
... )
>>> for user in user_list:
...    print(user.as_dict())
list_departments(query_params=None)

Returns the list of departments.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.limit_search] {bool}: Limits the search to match against the department name only. [query_params.search] {str}: Search string used to match against an admin/auditor user’s Login ID or Name. [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Specifies the page size.

The default size is 100, but the maximum size is 1000.

[query_params.sort_by] {str}: Sorts the departments based on available values.

Supported Values: id, name, expiry, status, external_id, rank

[query_params.sort_order] {str}: Sorts the order of departments based on available values

Supported Values: asc, desc, rule_execution

Returns:

A tuple containing (list of AdminUser instances, Response, error)

Return type:

tuple

Examples

List of departments:

>>> fetched_department, response, error = client.zia.user_management.get_department()
... if error:
...     print(f"Error fetching department by ID: {error}")
...     return
... print(f"Fetched department by ID: {fetched_department.as_dict()}")

Search specific department by name:

>>> fetched_department, response, error = client.zia.user_management.get_department(
    query_params={'search': 'Finance'})
... if error:
...     print(f"Error fetching department by ID: {error}")
...     return
... print(f"Fetched department by ID: {fetched_department.as_dict()}")
list_groups(query_params=None)

Returns the list of user groups.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.search] {str}: Search string used to match against an admin/auditor user’s Login ID or Name [query_params.defined_by] {str}: The string value defined by the group name or other applicable attributes [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Specifies the page size.

The default size is 100, but the maximum size is 1000.

[query_params.sort_by] {str}: Sorts the departments based on available values.

Supported Values: id, name, expiry, status, external_id, rank, mod_time

[query_params.sort_order] {str}: Sorts the order of departments based on available values

Supported Values: asc, desc, rule_execution

Returns:

A tuple containing (list of Groups instances, Response, error)

Return type:

tuple

Examples

List groups using default settings:

>>> group_list, response, error = client.zia.user_management.list_groups(
    query_params={'page_size': 2000})
... if error:
...     print(f"Error listing groups: {error}")
...     return
... print(f"Total groups found: {len(group_list)}")
... for group in group_list:
...     print(group.as_dict())
list_user_references(query_params=None)

Returns the list of Name-ID pairs for all users in the ZIA Admin Portal that can be referenced in user criteria within policies.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.include_admin_users] {bool}: Include the administrator users when retrieving the list. [query_params.name] {str}: Filters by user name. This is a starts with match. [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Specifies the page size.

The default size is 100, but the maximum size is 1000.

Returns:

A tuple containing (list of UserManagement instances, Response, error)

Return type:

tuple

Examples

List users using default settings:

>>> user_list, zscaler_resp, err = client.zia.user_management.list_users()
... if err:
...     print(f"Error listing users: {err}")
...     return
... print(f"Total users found: {len(user_list)}")
... for user in user_list:
...     print(user.as_dict())
list_users(query_params=None)

Returns the list of users.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.dept] {str}: Filters by department name. This is a starts with match. [query_params.group] {str}: Filters by group name. This is a starts with match. [query_params.name] {str}: Filters by user name. This is a starts with match. [query_params.page] {int}: Specifies the page offset.

[query_params.page_size] {int}: Specifies the page size.

The default size is 100, but the maximum size is 1000.

Returns:

A tuple containing (list of UserManagement instances, Response, error)

Return type:

tuple

Examples

List users using default settings:

>>> users_list, response, error = zia.users.list_users():
... if error:
...     print(f"Error listing users: {error}")
...     return
... for dept in department_list:
...     print(dept.as_dict())

List users, limiting to a maximum of 10 items:

>>> users_list, response, error = zia.users.list_users(query_params={'page_size': 10}):
... if error:
...     print(f"Error listing users: {error}")
...     return
... for dept in department_list:
...     print(dept.as_dict())
update_department(department_id, **kwargs)

Updates information for the specified ZIA Department.

Parameters:

department_id (int) – The unique ID for the RuDepartment.

Returns:

A tuple containing the updated Department, response, and error.

Return type:

tuple

update_group(group_id, **kwargs)

Updates information for the specified ZIA Group.

Parameters:

group_id (int) – The unique ID for the Group.

Returns:

A tuple containing the updated Group, response, and error.

Return type:

tuple

update_user(user_id, **kwargs)

Updates the details for the specified user.

Parameters:

  • user_id (str) – The unique identifier for the user.

  • **kwargs – Optional parameters to update the user details.

Keyword Arguments:

  • **adminUser (bool) – True if this user is an Admin user.

  • **comments (str) – Additional information about this user.

  • **department (dict, optional) – The updated department object.

  • **email (str, optional) – The updated email.

  • **groups (list of dict, optional) – The updated list of groups.

  • **name (str, optional) – The updated name.

  • **password (str) – User’s password (for Hosted DB authentication).

  • **tempAuthEmail (str) – Temporary Authentication Email.

  • **type (str) – User type (SUPERADMIN, ADMIN, AUDITOR, GUEST, etc.).

Returns:

A tuple containing the updated user object, response, and any error.

Return type:

tuple

Examples

Update the user name:

>>> zia.users.update_user('99999',
...      name='Joe Bloggs')

Update the email and add a comment:

>>> zia.users.update_user('99999',
...      name='Joe Bloggs',
...      comment='External auditor.')