User.search - Python API

Super-users may look up other users using several search criteria, such as display name, user ID or username. Consult the introduction to user search APIs for more information on how the parameters can be combined.

In Python, to find users, a zato.sso.SearchCtx object is created and filled in with the desired criteria, e.g. last name to find or pagination configuration.

On output, a list of results is returned, possibly empty or with one matching element only, along with metadata describing what is being returned, such as current page or total number of results. By default, all users are returned in groups of 50 per page.

Passwords are never returned on output.

SearchCtx has the following properties that can be set and none of them is required.

Name	Datatype	Default	Notes
user_id	string	---	ID of user to find (will match either one or no user)
username	string	---	Username (ditto)
email	string	---	E-mail (There is no requirement that it be unique)
display_name	string	---	Match by display name
first_name	string	---	Match by first name
middle_name	string	---	Match by middle name
last_name	string	---	Match by last name
sign_up_status	string	---	User's sign up status, must be one of`: before_confirmation, to_approve, final
approval_status	string	---	User's approval status, must be one of`: before_decision, approved, rejected
paginate	bool	True	Should the results be paginated
cur_page	int	1	Current page to return from a list of result pages (counted from 1)
page_size	int	50	How many results to return on a single page
name_op	string	`zato.sso.const.search.and_`	How to join name criteria (display/first/middle/last name), by AND or OR
is_name_exact	bool	True	Are name criteria considered exact values to match or are they sub-strings

self.sso.user.search

search(self, cid, ctx, current_ust, current_app, remote_addr)

Looks up users by input criteria and returns a list of results, possibly empty or with only one matching user.

cid: Correlation ID used by audit log
ctx: Search configuration
current_ust: Current user's UST
current_app: Name of application the current user is issuing the call from
remote_addr: User's remote address
Returns: A dictionary of metadata describing the result and a list of results

On output, all of the keys pertaining to metadata will always exist:

Key	Datatype	Notes
total	int	How many users matched input criteria in total
num_pages	int	How many pages of results there are (counted from 1)
page_size	int	What is the size of an individual page (rewritten from input)
cur_page	int	What is the current page that is returned (counted from 1)
has_next_page	bool	Is there a next page to navigate to
has_prev_page	bool	Is there a previous page to navigate to
next_page	int	What is the next page to navigate to (counted from 1 and applicable only if has_next_page is True)
prev_page	int	What is the previous page to navigate to (counted from 1 and applicable only if has_prev_page is True)

Each element in the list of results is a zato.sso.User object, representing a particular user, with attributes as below. Further, the object's .to_dict() method will serialize all the data to a Python dictionary.

Name	Datatype	Optional	Notes
user_id	string	---	ID of the user returned
username	string	---	Username of the user
email	string	Yes	E-mail
display_name	string	Yes	Display name
first_name	string	Yes	First name
middle_name	string	Yes	Middle name
last_name	string	Yes	Last name
is_totp_enabled	bool	Yes	Should TOTP-based two factor authentication be enabled for user
totp_key	string	Yes	Auto-generated User's TOTP key, one will be auto-generated for user if it is not given on input, even if is_totp_enabled is False
totp_label	string	Yes	An arbitrary label assigned to user's TOTP key for convenience
is_active	bool	Yes	(Reserved for future use)
is_internal	bool	Yes	Does the account belong to Zato internally?
is_super_user	bool	Yes	Is the user a super-user?
is_approval_needed	bool	Yes	Is a super-user's approval needed for this account to become fully active?
approval_status	string	Yes	Current approval status, one of`: before_decision, approved, rejected
approval_status_mod_by	string	Yes	By whom the approval status was last changed, will be 'auto' for users created from command line
approval_status_mod_time	datetime	Yes	When was the approval status last changed
is_locked	bool	Yes	Has this account been locked by a super-user?
locked_time	string	Yes	If locked, when was it?
locked_by	string	Yes	If locked, who by?
creation_ctx	string	Yes	(Reserved for future use)
approv_rej_time	string	Yes	If approved or rejected, when was it?
approv_rej_by	string	Yes	If approved or rejected, who by?
password_expiry	string	Yes	When will that account's password expire?
password_is_set	bool	Yes	(Reserved for future use)
password_must_change	bool	Yes	Is the user required to change password on next login?
password_last_set	string	Yes	When was the password last set?
sign_up_status	string	Yes	Signup process status, returned values are`: before_confirmation, to_approve, final
sign_up_time	datetime	Yes	When did the user sign up with the system?

# -*- coding: utf-8 -*-

# stdlib
from datetime import datetime, timedelta
from logging import getLogger
from random import randint

# Zato
from zato.server.service import Service
from zato.sso import SearchCtx

class UserSearch(Service):
    def handle(self):

        username = 'admin1'
        password = '<password>'
        session = self.sso.user.login(
                username, password, 'CRM', '127.0.0.1', 'My UA', False, False)

        # Search data
        ctx = SearchCtx()
        ctx.last_name = 'smith'
        ctx.page_size = 2
        ctx.cur_page = 2

        data = self.sso.user.search(self.cid, ctx, session.ust, 'CRM', '127.0.0.1')

        # Log metadata
        self.logger.info('total.................... %s', data['total'])
        self.logger.info('num_pages................ %s', data['num_pages'])
        self.logger.info('page_size................ %s', data['page_size'])
        self.logger.info('cur_page................. %s', data['cur_page'])
        self.logger.info('has_next_page............ %s', data['has_next_page'])
        self.logger.info('has_prev_page............ %s', data['has_prev_page'])
        self.logger.info('next_page................ %s', data['next_page'])
        self.logger.info('prev_page................ %s', data['prev_page'])

        # Log users found
        for row in data['result']:
            self.logger.info('.' * `60)
            for key, value in sorted(row.to_dict().items()):
                self.logger.info('%s %s', key.ljust(25), value)

INFO - total.................... 6
INFO - num_pages................ 3
INFO - page_size................ 2
INFO - cur_page................. 2
INFO - has_next_page............ True
INFO - has_prev_page............ True
INFO - next_page................ 3
INFO - prev_page................ 1
INFO - ............................................................
INFO - approval_status           approved
INFO - approval_status_mod_by    zusr69g59s4x3v9n1bwj978vfnf330
INFO - approval_status_mod_time  2023-03-10 17:41:04
INFO - creation_ctx              None
INFO - display_name              Judith Smith
INFO - email                     None
INFO - first_name                Judith
INFO - is_active                 True
INFO - is_internal               False
INFO - is_locked                 False
INFO - is_super_user             False
INFO - last_name                 Smith
INFO - locked_by                 None
INFO - locked_time               None
INFO - middle_name               None
INFO - password_expiry           2020-03-09 17:41:03
INFO - password_is_set           True
INFO - password_last_set         2023-03-10 17:41:03
INFO - password_must_change      False
INFO - sign_up_status            final
INFO - sign_up_time              2023-03-10 17:41:03
INFO - user_id                   zusr3yqm708em08yn9tqmff5n1dkb6
INFO - username                  judith.smith
INFO - ............................................................
INFO - approval_status           approved
INFO - approval_status_mod_by    zusr69g59s4x3v9n1bwj978vfnf330
INFO - approval_status_mod_time  2023-03-10 17:38:17
INFO - creation_ctx              None
INFO - display_name              Paul Greensmith
INFO - email                     None
INFO - first_name                Paul
INFO - is_active                 True
INFO - is_internal               False
INFO - is_locked                 False
INFO - is_super_user             False
INFO - last_name                 Greensmith
INFO - locked_by                 None
INFO - locked_time               None
INFO - middle_name               None
INFO - password_expiry           2020-03-09 17:38:16
INFO - password_is_set           True
INFO - password_last_set         2023-03-10 17:38:16
INFO - password_must_change      False
INFO - sign_up_status            final
INFO - sign_up_time              2023-03-10 17:38:16
INFO - user_id                   zusr3ny5pfyn4p8xp8ftp0yryjszms
INFO - username                  paul.greensmith