Accounts

In the following table, Account design a PrivilegedAccount object described below.

Section overview
Section	Description
Finding accounts	Search and find accounts in the vault
Creating accounts	Create accounts
Account management	get, update, link, delete and move accounts
Password Actions	Change, reconcile, verify, set or get passwords
Password management	Disable or resume password management, get CPM Status
Account Group membership	Add or remove account to an account group
Miscellaneous	Other account related function, connect, get ID, find FC path…

The PrivilegedAccount Class

PrivilegedAccount is a Python class that represent a Cyberark Account to avoid dictionary manipulation in code. Most of the following function works with objects of this class. It was made the most generic possible, however you can completely customize it you way using inheritance.

It has the following mandatory attributes:

name: Cyberark name of the account (eg unixsrv01-dbadmin).
platformId: ID of the platform (eg UnixSSH).
safeName: The safe in which the account is stored (eg DBA-Safe).

It has the following extra attributes:

userName: Username of the account (eg dbadmin)
address: Address of the account (eg unixsev01)
id: Cyberark unique ID of the account (eg 12-451)
secret: The password of the account
secretManagement: A dictionary with the secret management infos
secretType: The type of password (“password” or “key”)
platformAccountProperties: A dictionary with all optional file categories
remoteMachinesAccess: A dictionary with the remote machines access infos

it has the following methods :

get_name : return the computed name “address-username”
to_json: return a dict representation of the Object
cpm_status: return the CPM status of the account
last_modified : return the last modified time (days since last password change)

About linked account index :

reconcile account index: 3 - you should NOT change it unless your system has different custom value.
logon account index: 2 - this is different from the installation (1). The default value is kept at 2 to avoid breaking existing users. You can override it to 1 by providing a “custom.LOGON_ACCOUNT_INDEX” value in your config.

Calling functions

When it’s possible, functions support call with a list as argument instead of single item argument.
You should try to use list to have the maximum benefit from the async implementation.
The return of a function called with a list is a list of applied function in the same order the initial list was given.
If an exception is raised for an item, the exception will be returned as a member of the list (and not raised directly).

Finding accounts

async search_account_by(keywords=None, username=None, address=None, safe=None, platform=None, **kwargs) → list

This function allow to search using one or more parameters and return list of address id.
This is the easiest way to retrieve accounts from the vault.
It allows you to either search on given keywords, or more precisely on an account attribute.

For example:

accounts = await search_account_by(username="admin", safe="Linux-SRV", my_custom_FC="Database")

Parameters:

keywords – free search
username – username search (field “userName”)
address – IP address search (field “address”)
safe – search in particular safe
platform – search by platform name (no space) (field “platformId”)
kwargs – any searchable key = value

Returns:

A list of PrivilegedAccounts

⚠️ Note: This function doesn’t populate the secret field (password), you have to make a separated call if you want to get it.

async search_account(self, expression: str)

This function search an address using free text search and return a list a Privileged Account objects

Parameters:: expression – List of keywords to search for in accounts, separated by a space.
Returns:: List of PrivilegedAccount objects

ℹ️ See also search_account_by function

async search_account_iterator(self, keywords=None, username=None, address=None, safe=None, platform=None, **kwargs) → AsyncIterator[PrivilegedAccount]

This function allow to search using one or more parameters and return list of address id.

Parameters:

keywords – free search
username – username search (field “userName”)
address – IP address search (field “address”)
safe – search in particular safe
platform – search by platform name (no space) (field “platformId”)
kwargs – any searchable key = value

Returns:

an async generator of PrivilegedAccounts

ℹ️ See also search_account_by

async search_account_paginate(self, page: int = 1, size_of_page: int = 1000, safe: str = None, search: str = None, **kwargs)

Search accounts in a paginated way

Parameters:

search – free search
page – The page number (starting at 1)
size_of_page – the size of pages (max 1000)
safe – the safe name, if wanted
kwargs – whatever file category you want to find

Returns:

A dictionary with keys:

accounts : This is a list of matched account for the given page
has_next_page : A boolean hat indicated if there is a next page

ℹ️ For your convenience you can use platform=”PF-NAME” instead of platformID (and thus if you have a custom “platform” FC it will not be considered).

async search_account_by_ip_addr(self, address: PrivilegedAccount | str)

This function will search an account by IP address by checking if “address” is a valid IPv4 address and checking if “Address” property of the account is exactly the given address. You can also provide an PrivilegedAccount, the function will search on its address property

Parameters:: address – A PrivilegedAccount object or IPv4 valid address
Returns:: A list of “PrivilegedAccount” objects

Creating accounts

async add_account_to_safe(self, account: PrivilegedAccount | List[PrivilegedAccount]) → str

This function support list of PrivilegedAccount as argument

This function creates the PrivilegedAccount (or the list of PrivilegedAccount) in the account’s safe (the safe attribute of the account). If the account(s) already exists, then raises a CyberarkAPIException

Parameters:: account – PrivilegedAccount or list ofPrivilegedAccount
Returns:: account_id or list(account_id | exceptions)
Raises:: CyberarkAPIException – If there is something wrong

Account management

async update_file_category(self, account, file_category, new_value)

Update the file category (or list of FC) with the new value (or list of new values) If the FC does not exist, it will create it

Parameters:

account – address, list of accounts, account_id, list of accounts id
file_category – a file category or a list of file category
new_value – the new value of the list of new values

async update_platform(self, account: PrivilegedAccount | List[PrivilegedAccount], new_platform: str)

This function updates the account’s (or list) platform

Parameters:

account – PrivilegedAccount, list of Privileged Accounts
new_platform – The new plaform ID (e.g. Unix-SSH)

Returns:

True if succeeded

async update_single_fc(self, account, file_category, new_value, operation='replace')

Update / Delete / Create a File Category for an account or a list of accounts The path of the file_category is (hopefully) automatically detected

Parameters:

account – address, list of accounts, account_id, list of accounts id
file_category – the File Category to update
new_value – The new value of the FC
operation – Replace, Remove or Add

Returns:

The updated PrivilegedAccount or the list of updated PrivilegedAccount

Raises:

AiobastionException – if the FC was not found in the Vault
CyberarkAPIException – if another error occured

async update_using_list(self, account, data) → PrivilegedAccount | List[PrivilegedAccount]

This function support list of PrivilegedAccount as argument

This function updates an account (or list) with the data list of changes. For more infos, check CyberArk doc.

Valid operations are : Replace, Remove or Add

For example:

# insert here logon to vault and retrieve an account
data = [
    {"path": "/name", "op": "replace", "value": new_name},
    {"path": "/address", "op": "replace", "value": new_address},
    {"path": "/platformId", "op": "replace", "value": new_platformId},
]
is_updated = await epv.account.update_using_list(account, data)

Parameters:

account – address, list of accounts, account_id, list of accounts id
data – The list of FC to change.

Returns:

The updated PrivilegedAccount or the list of updated PrivilegedAccount

async move(self, account: PrivilegedAccount | List[PrivilegedAccount], new_safe: str)

Delete the account (or list) and recreate it (or them) in with the same parameters and password in the new safe.

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
new_safe – New safe to move the account(s) into

Returns:

Boolean that indicates if the operation was successful

async link_account(self, account: PrivilegedAccount, link_account: PrivilegedAccount, extra_password_index: int, folder='Root') → bool

Links the account of the given PrivilegedAccount (or the list of accounts) to the given PrivilegedAccount

Parameters:

account – The target address
link_account – The linked address (reconcile or logon address)
extra_password_index – 1 for logon, 3 for reconcile
folder – “Root” by default

Returns:

True if success, exception otherwise

async link_logon_account(self, account: PrivilegedAccount | List[PrivilegedAccount], logon_account: PrivilegedAccount)

This function links the account (or the list of accounts) to the given logon account

⚠️ The “logon” Account is supposed to have an index of 2

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
logon_account – The logon PrivilegedAccount object

Returns:

A boolean that indicates if the operation was successful.

Raises:

CyberarkException – If link failed

async link_reconciliation_account(self, account: PrivilegedAccount | List[PrivilegedAccount], reconcile_account: PrivilegedAccount)

This function links the account (or the list of accounts) to the given reconcile account

⚠️ The “reconcile” Account is supposed to have an index of 3

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
reconcile_account – The reconciliation PrivilegedAccount object

Returns:

A boolean that indicates if the operation was successful.

Raises:

CyberarkException – If link failed

async link_reconcile_account_by_address(self, acc_username, rec_acc_username, address)

This function links the account with the given username and address to the reconciliation account with the given rec_account_username and the given address

Parameters:

acc_username – username of the account to link
rec_acc_username – username of the reconciliation account
address – address of both accounts

Returns:

A boolean that indicates if the operation was successful.

Raises:

CyberarkException – If link failed

async unlink_account(self, account: PrivilegedAccount | List[PrivilegedAccount], extra_password_index: int)

This function unlinks the account of the given account (or the list of accounts) | ⚠️ Double-check the linked account index on your platform.

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
extra_password_index – The index of the account that must be unlinked

Returns:

A boolean that indicates if the operation was successful.

Raises:

CyberarkException – If link failed:

async remove_logon_account(self, account: PrivilegedAccount | List[PrivilegedAccount])

This function unlinks the logon account of the given account (or the list of accounts)
⚠️ The “logon” Account index is default to 2 but can be set differently on the platform
You can change it by setting custom:LOGON_ACCOUNT_INDEX in your config file

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: A boolean that indicates if the operation was successful.
Raises:: CyberarkException – If link failed:

async remove_reconcile_account(self, account: PrivilegedAccount | List[PrivilegedAccount])

This function unlinks the reconciliation account of the given account (or the list of accounts)
⚠️ The “reconcile” Account is supposed to have an index of 3
You can change it by setting custom:RECONCILE_ACCOUNT_INDEX in your config file

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: A boolean that indicates if the operation was successful.
Raises:: CyberarkException – If link failed:

async delete(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str])

This function support list of PrivilegedAccount as argument

This deletes the account (or list).

⚠️ If this is an SSH Key, this function will delete it on the Vault but not on systems!

Parameters:: account – PrivilegedAccount or list(PrivilegedAccount) to delete
Returns:: True if succeeded
Raises:: CyberarkException – If delete failed

Password Actions

async change_password(self, account: PrivilegedAccount | str, change_group=False)

This function set the account (or list) for immediate change.

Keep in mind that for list, exceptions are returned and not raised.

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
change_group – change entire group, default to False

Returns:

A boolean that indicates if the operation was successful.

Raises:

CyberarkException – If change failed

async reconcile(self, account: PrivilegedAccount | str)

This function set the account (or list) for immediate reconciliation.

Keep in mind that for list, exceptions are returned and not raised.

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: A boolean that indicates if the operation was successful.
Raises:: CyberarkException – If reconciliation failed

async verify(self, account: PrivilegedAccount | str)

This function set the account (or list) for immediate verification.

Keep in mind that for list, exceptions are returned and not raised.

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: A boolean that indicates if the operation was successful.
Raises:: CyberarkException – If verify failed

async get_secret(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str])

Get the secret of an account, detecting if the secret type is password or key

Parameters:: account – A PrivilegedAccount object, or a list of PrivilegedAccount objects
Returns:: The password, key or list of passwords / keys.

async get_password(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str], reason: str = None)

Retrieve the password of an address

✅ Use get_secret instead if you want to retrieve password or ssh_key

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
reason – The reason that is required to retrieve the password

Returns:

Account password value (or list of passwords)

Raises:

CyberarkException – If retrieve failed

async get_password_aim(self, **kwargs)

Retrieve secret password from the Central Credential Provider (AIM) GetPassword Web Service information.

ℹ️ The following parameters are optional searchable keys, see CyberArk documentation in: Developer/Central Credential Provider/Call the Central Credential Provider Web Service …/REST

Parameters:

username – User account name
safe – Safe where the account is stored.
object – Name of the account to retrieve (unique for a specific safe).
folder – Name of the folder property
address – Address account property
database – Database account property
policyid – Policy account property
reason – The reason for retrieving the password. This reason will be audited in the Credential Provider audit log.
query – Defines a free query using account properties, including Safe, folder, and object. When this method is specified, all other search criteria (Safe/Folder/ Object/UserName/Address/PolicyID/Database) are ignored and only the account properties that are specified in the query are passed to the Central Credential Provider in the password request.
queryformat – Defines the query format, which can optionally use regular expressions. Possible values are: Exact or Regexp
failrequestonpasswordchange – Boolean, Whether or not an error will be returned if this web service is called when a password change process is underway.

Returns:

namedtuple of (secret, detail)

secret = password

detail = dictionary from the Central Credential Provider (AIM) GetPassword Web Service.

Raises:

CyberarkAIMnotFound – Account not found
CyberarkAPIException – HTTP error or CyberArk error
CyberarkException – Runtime error
AiobastionException – AIM configuration setup error

async get_secret_aim(self, account: PrivilegedAccount | List[PrivilegedAccount], reason: str = None)

This function support list of PrivilegedAccount as argument

This function update the secret attribute of the PrivilegedAccount with the password returned by the AIM Web service. If the account is not found, the secret is set to None.

Parameters:

account (PrivilegedAccount, list) – A PrivilegedAccount object, or a list of PrivilegedAccount objects
reason – The reason for retrieving the password. This reason will be audited in the Credential Provider audit log. (optional)

Returns:

PrivilegedAccount Object updated, if the password is not found the secret will be None

Raises:

CyberarkAPIException – HTTP error or CyberArk error
CyberarkException – Runtime error
AiobastionException – AIM configuration setup error

async get_ssh_key(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str])

Retrieve the SSH Key of an account

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: SSH key value, or a list of ssh key values

async get_secret_versions(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str], reason: str = None)

Retrieve the secret versions

Parameters:

account – Privileged Account or address id
reason – The reason that is required to retrieve the password

Returns:

Account password value

async set_password(self, account, password)

Set the password for the given address in the Vault

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
password – new password to set

Returns:

True if success

Raises:

CyberarkException – If set password failed (your platform enforce complexity, or you don’t have rights)

async set_next_password(self, account, password)

Set the next password for the given address to be set by the CPM

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
password – new password to set

Returns:

True if change was successfully planned.

async restore_last_cpm_version(self, account: PrivilegedAccount, cpm)

Find in the history of passwords the last password set by the CPM and updates the password accordingly in the Vault

Parameters:

account – a PrivilegedAccount object
cpm – the name of the CPM who set the password

Returns:

True if success

Raises:

AiobastionException – if no CPM version was found

async restore_last_cpm_version_by_cpm(self, account: PrivilegedAccount, cpm)

Find in the history of passwords the last password set by the CPM and schedule a password change with this value

Parameters:

account – a PrivilegedAccount object
cpm – the name of the CPM who set the password

Returns:

True if success

Raises:

AiobastionException – if there is no CPM version for this account

Password management

async disable_password_management(self, account: PrivilegedAccount | List[PrivilegedAccount], reason: str = '')

This disables the account (or list) password management

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
reason – The reason of disabling password management (defaults to empty string)

Returns:

The list of updated accounts, or exceptions

Raises:

CyberarkException – If disabling failed.

async resume_password_management(self, account: PrivilegedAccount | List[PrivilegedAccount])

This resume the account (or list) password management

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: The list of updated accounts, or exceptions
Raises:: CyberarkException – If resuming failed.

async get_cpm_status(self, account: PrivilegedAccount | List[PrivilegedAccount])

Get the CPM status of an account or a list of accounts.

✅ You can also use the cpm_status() method of the object PrivilegedAccount

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: The secretManagement dictionary of the account.

async activity(self, account: PrivilegedAccount | List[PrivilegedAccount])

Get account(s) activity

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: The activity dictionary as-is it is returned by CyberArk
Raises:: CyberarkException – If call failed

async last_cpm_error_message(self, account: PrivilegedAccount | List[PrivilegedAccount])

Get the last CPM Error message

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: The last CPM error status, or None
Raises:: CyberarkException – If link failed

Account Group membership

async get_account_group(self, account: PrivilegedAccount | List[PrivilegedAccount])

Returns the GroupID of a given PrivilegedAccount

To get the group name, and more, check the Account Group section of this documentation.

Parameters:: account (PrivilegedAccount, list) – PrivilegedAccount, list of Privileged Accounts
Returns:: GroupID (which is not the group name)

async add_member_to_group(self, account: PrivilegedAccount | List[PrivilegedAccount], group_name: str = '') → str

This function support list of PrivilegedAccount as argument Add an address to a group

Parameters:

account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
group_name – name of the group (or try the address username if empty)

Returns:

AccountID

async del_account_group_membership(self, account: PrivilegedAccount | List[PrivilegedAccount])

Find and delete the account_group membership of a PrivilegedAccount (or list)

Parameters:: account (PrivilegedAccount, list) – a PrivilegedAccount object or a list of PrivilegedAccount objects
Returns:: False if no group was remove, True is a group was deleted
Raises:: CyberarkAPIException – if a group was found but deletion didn’t work

Miscellaneous

async connect_using_PSM(self, account, connection_component, reason: str = '')

This function returns a file content (bytes) which is the equivalent RDP file of the “Connect” button

For example:

async with production_vault as epv:
    # find first active connexion component
    try:
        unique_id = await epv.platform.get_target_platform_unique_id(account.platformId)
        ccs = await epv.platform.get_target_platform_connection_components(unique_id)
        cc = None
        for _cc in ccs:
            if _cc["Enabled"]:
                cc = _cc["PSMConnectorID"]
                break
    except CyberarkException as err:
        # You are not Vault Admin
        self.assertIn("PASWS041E", str(err))

    rdp_content = await epv.account.connect_using_PSM(account.id, cc)
    with open("connect_account.rdp", "w") as rdp_file:
        rdp_file.write(rdp_content)

Parameters:

account – PrivilegedAccount or account_id
connection_component – the connection component to connect with
reason – the reason that is required to request access to this account

Returns:

file_content

Raises:

CyberarkAPIException – if an error occured

detect_fc_path(self, fc: str)

Detect the path of the File Category

Parameters:: fc – the name of the File Category
Returns:: The string representing the Path to the FC

async get_account(self, account_id) → PrivilegedAccount | List[PrivilegedAccount]

This function support list of PrivilegedAccount as argument

This function returns a Privileged account object for a given account_id (or list of account_id)

Parameters:: account_id – account_id or list(account_id)
Returns:: PrivilegedAccount or list(PrivilegedAccount | exceptions)
Raises:: CyberarkException – 404 if the account doesn’t exist.

async get_account_id(self, account: PrivilegedAccount | str | List[PrivilegedAccount] | List[str])

Internal function to get account ID

Parameters:: account – PrivilegedAccount object (or account_id) or list of mixed PrivilegedAccount and account_id
Returns:: account_id or list of account_id

is_valid_safename(self, name: str) → bool

Check if the safename is a valid Vault safe name.

Parameters:: name – Safe name to check
Returns:: A boolean that indicates whether the username if valid or not.

is_valid_username(self, username: str) → bool

Check if the username is a valid Vault username

Parameters:: username – username to check
Returns:: A boolean that indicates whether the username if valid or not.