admin_users

The following methods allow for interaction with the ZIA Admin User Management API endpoints.

Methods are accessible via zia.admin_users

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 AdminUsersAPI

Bases: APIClient

A Client object for the Admin and Role resource.

add_admin_user(name, login_name, email, password, **kwargs)

Adds a new admin user to ZIA.

Parameters:

  • name (str) – The user’s full name.

  • login_name (str) – The name that the admin user will use to login to ZIA in email format, i.e. user@domain.tld.

  • email (str) – The email address for the admin user.

  • password (str) – The password for the admin user.

  • associate_with_existing_admin (bool) – This field is set to true to update an admin user that already exists.

Keyword Arguments:

  • admin_scope_type (str) – The scope of the admin’s permissions, accepted values are: ORGANIZATION, DEPARTMENT, LOCATION, LOCATION_GROUP

  • comments (str) – Additional information about the admin user.

  • disabled (bool) – Set to True if you want the account disabled upon creation.

  • is_password_login_allowed (bool) – Set to True to allow password login.

  • is_security_report_comm_enabled (bool) – Set to True to allow ZIA Security Update emails to be sent to the admin user.

  • is_service_update_comm_enabled (bool) – Set to True to allow ZIA Service Update emails to be sent to the admin user.

  • is_product_update_comm_enabled (bool) – Set to True to allow ZIA Product Update emails to be sent to the admin user.

  • is_password_expired (bool) – Set to True to expire the admin user’s password upon creation.

  • is_exec_mobile_app_enabled (bool) – Set to True to enable to executive insights mobile application for the admin user.

  • role_id (int) – The unique id for the admin role being assigned to the admin user.

  • scope_entity_ids (list) – A list of entity ids for the admin user’s scope. e.g. if the admin user has admin_scope set to department then you will need to provide a list of department ids. NOTE: This param doesn’t need to be provided if the admin user’s scope is set to ORGANIZATION.

Returns:

The newly created admin user resource record.

Return type:

Tuple

Examples

Add an admin user with the minimum required params:
>>> add_admin_user, _, error = client.zia.admin_users.add_admin_user(
...    name="Jim Bob",
...    login_name="jim@example.com",
...    password="*********",
...    email="jim@example.com")
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {add_admin_user.as_dict()}")
Add an admin user with a department admin scope type:
>>> add_admin_user, _, error = client.zia.admin_users.add_admin_user(
...    name="Jane Bob",
...    login_name="jane@example.com",
...    password="*********",
...    email="jane@example.com,
...    role_id=84546,
...    admin_scope_type="DEPARTMENT",
...    scope_entity_ids = ['376542', '245688']
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {add_admin_user.as_dict()}")
Add an auditor user:
>>> add_admin_user = zia.admin_users.add_admin_user(
...    name="Head Bob",
...    login_name="head@example.com",
...    password="*********",
...    email="head@example.com,
...    is_auditor=True,
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {add_admin_user.as_dict()}")
convert_to_user(user_id, query_params=None, **kwargs)

Removes admin privileges for a user while retaining them as a regular user of your organization in the ZIA Admin Portal. This can be used as an alternative to the delete_admin_user method.

Parameters:

  • user_id (int) – The unique ID for the User.

  • name (str) – User name. This appears when choosing users for policies. The name field allows values containing UTF-8 characters up to a maximum of 127 characters.

  • email (str) – User email consists of a user name and domain name.

  • groups (list) – List of Groups a user belongs to. Groups are used in policies.

  • department (dict) – Department a 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.

Returns:

The resource record for the converted user.

Return type:

Tuple

Examples

Add a user with the minimum required params:

>>> user, zscaler_resp, err = zia.users.convert_to_user(name='Jane Doe',
...    user_id=99999
...    email='jane.doe@example.com',
...    groups=[{
...      'id': '49916183'}]
...    department={
...      'id': '49814321'})
delete_admin_user(user_id)

Deletes the specified admin user by id.

Parameters:

user_id (str) – The unique id of the admin user.

Returns:

The response code for the request.

Return type:

int

Examples

>>> _, _, error = client.zia.admin_users.delete_admin_user(143783113)
>>> if error:
...     print(f"Error deleting admin user: {error}")
...     return
... print(f"Admin User with ID {143783113} deleted successfully")
get_admin_user(user_id)

Returns information on the specified admin user id.

Parameters:

  • user_id (str) – The unique id of the admin user.

  • {dict} (query_params) – Map of query parameters for the request.

Returns:

A tuple containing (AdminUser instance, Response, error)

Return type:

tuple

Examples

>>> fetched_user, _, error = client.zia.admin_users.get_admin_user(143783113)
>>> if error:
...     print(f"Error fetching admin user by ID: {error}")
...     return
... print(f"Fetched Admin user by ID: {fetched_user.as_dict()}")
list_admin_users(query_params=None)

Returns a list of admin users.

Note: For tenants migrated to Zidentity this endpoint will return an empty list.

Parameters:

{dict} (query_params) –

Map of query parameters for the request.

[query_params.include_auditor_users] {bool}: Include or exclude auditor user information in the list.

[query_params.include_admin_users] {bool}: Include or exclude admin user information in the list.

[query_params.search] {str}: Search string to partially match 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.

Returns:

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

Return type:

tuple

Examples:

List All Admin users
>>> list_users, _, error = client.zia.admin_users.list_admin_users()
>>>     if error:
...         print(f"Error listing admin users: {error}")
...         return
...     print(f"Total admin users found: {len(list_users)}")
...     for users in list_users:
...         print(users.as_dict())
List All Admin users Including auditor users
>>> list_users, _, error = client.zia.admin_users.list_admin_users(
    query_params={'include_auditor_users': True}
)
>>>     if error:
...         print(f"Error listing admin users: {error}")
...         return
...     print(f"Total admin users found: {len(list_users)}")
...     for users in list_users:
...         print(users.as_dict())
update_admin_user(user_id, **kwargs)

Update an admin user.

Parameters:

  • user_id (str) – The unique id of the admin user to be updated.

  • **kwargs – Optional keyword args.

Keyword Arguments:

  • admin_scope_type (str) – The scope of the admin’s permissions, accepted values are: ORGANIZATION, DEPARTMENT, LOCATION, LOCATION_GROUP

  • comments (str) – Additional information about the admin user.

  • disabled (bool) – Set to True if you want the account disabled upon creation.

  • email (str) – The email address for the admin user.

  • is_password_login_allowed (bool) – Set to True to allow password login.

  • is_security_report_comm_enabled (bool) – Set to True to allow ZIA Security Update emails to be sent to the admin user.

  • is_service_update_comm_enabled (bool) – Set to True to allow ZIA Service Update emails to be sent to the admin user.

  • is_product_update_comm_enabled (bool) – Set to True to allow ZIA Product Update emails to be sent to the admin user.

  • is_password_expired (bool) – Set to True to expire the admin user’s password upon creation.

  • is_exec_mobile_app_enabled (bool) – Set to True to enable to executive insights mobile application for the admin user.

  • name (str) – The user’s full name.

  • password (str) – The password for the admin user.

  • role_id (int) – The unique id for the admin role being assigned to the admin user.

  • scope_entity_ids (list) – A list of entity ids for the admin user’s scope. e.g. if the admin user has admin_scope set to department then you will need to provide a list of department ids. NOTE: This param doesn’t need to be provided if the admin user’s scope is set to ORGANIZATION.

Returns:

The updated admin user resource record.

Return type:

dict

Examples

Update an admin user with the minimum required params:
>>> update_admin_user, _, error = client.zia.admin_users.update_admin_user(
...    user_id=143783113,
...    name="Jim Bob",
...    login_name="jim@example.com",
...    password="*********",
...    email="jim@example.com")
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {update_admin_user.as_dict()}")
Update an admin user with a department admin scope type:
>>> update_admin_user, _, error = client.zia.admin_users.update_admin_user(
...    user_id=143783113,
...    name="Jane Bob",
...    login_name="jane@example.com",
...    password="*********",
...    email="jane@example.com,
...    role_id=84546,
...    admin_scope_type="DEPARTMENT",
...    scope_entity_ids = ['376542', '245688']
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {add_admin_user.as_dict()}")
Update an auditor user:
>>> update_admin_user = zia.admin_users.add_admin_user(
...    user_id=143783113,
...    name="Head Bob",
...    login_name="head@example.com",
...    password="*********",
...    email="head@example.com,
...    is_auditor=True,
...     )
>>>     if error:
...         print(f"Error adding admin user: {error}")
...         return
...     print(f"Admin User added successfully: {add_admin_user.as_dict()}")