cyberark.pas.cyberark_account – Module for CyberArk Account object creation, deletion, and modification using PAS Web Services SDK.

Note

This plugin is part of the cyberark.pas collection (version 1.0.6).

To install it use: ansible-galaxy collection install cyberark.pas.

To use it in a playbook, specify: cyberark.pas.cyberark_account.

New in version 2.4: of cyberark.pas

Synopsis

  • Creates a URI for adding, deleting, modifying a privileged credential within the Cyberark Vault. The request uses the Privileged Account Security Web Services SDK.

Parameters

Parameter Choices/Defaults Comments
address
string
The address of the endpoint where the privileged account is located.
api_base_url
string / required
A string containing the base URL of the server hosting CyberArk's Privileged Account Security Web Services SDK.
cyberark_session
dictionary / required
Dictionary set by a CyberArk authentication containing the different values to perform actions on a logged-on CyberArk session, please see cyberark_authentication module for an example of cyberark_session.
identified_by
string
Default:
"username,address,platform_id"
When an API call is made to Get Accounts, often times the default parameters passed will identify more than one account. This parameter is used to confidently identify a single account when the default query can return multiple results.
logging_file
string
Default:
"/tmp/ansible_cyberark.log"
Setting the log file name and location for troubleshooting logs.
logging_level
string / required
    Choices:
  • NOTSET
  • DEBUG
  • INFO
Parameter used to define the level of troubleshooting output to the logging_file value.
name
string
The ObjectID of the account
new_secret
string
The new secret/password to be stored in CyberArk Vault.
platform_account_properties
dictionary
Object containing key-value pairs to associate with the account, as defined by the account platform. These properties are validated against the mandatory and optional properties of the specified platform's definition. Optional properties that do not exist on the account will not be returned here. Internal properties are not returned.
KEY
string
Freeform key value associated to the mandatory or optional property assigned to the specified Platform's definition.

aliases: Port, ExtrPass1Name, database
platform_id
string
The PolicyID of the Platform that is to be managing the account
remote_machines_access
dictionary
Set of parameters for defining PSM endpoint access targets.
access_restricted_to_remote_machines
boolean
    Choices:
  • no
  • yes
Whether or not to restrict access only to specified remote machines.
remote_machines
string
List of targets allowed for this account.
safe
string / required
The safe in the Vault where the privileged account is to be located.
secret
string
The initial password for the creation of the account
secret_management
dictionary
Set of parameters associated with the management of the credential.
automatic_management_enabled
boolean
    Choices:
  • no ←
  • yes
Parameter that indicates whether the CPM will manage the password or not.
management_action
string
    Choices:
  • change
  • change_immediately
  • reconcile
CPM action flag to be placed on the account object for credential rotation.
manual_management_reason
string
String value indicating why the CPM will NOT manage the password.
new_secret
string
The actual password value that will be assigned for the CPM action to be taken.
perform_management_action
string
    Choices:
  • always ←
  • on_create
always will perform the management action in every action.
on_create will only perform the management action right after the account is created.
secret_type
string
    Choices:
  • password ←
  • key
The value that identifies what type of account it will be.
state
string / required
    Choices:
  • present ←
  • absent
Assert the desired state of the account present to creat or update and account object. Set to absent for deletion of an account object.
username
string
The username associated with the account.
validate_certs
boolean
    Choices:
  • no
  • yes ←
If false, SSL certificate chain will not be validated. This should only set to true if you have a root CA certificate installed on each node.

Examples

collections:
  - cyberark.pas

tasks:

  - name: Logon to CyberArk Vault using PAS Web Services SDK
    cyberark_authentication:
      api_base_url: "http://components.cyberark.local"
      validate_certs: no
      username: "bizdev"
      password: "Cyberark1"

  - name: Creating an Account using the PAS WebServices SDK
    cyberark_account:
      logging_level: DEBUG
      identified_by: "address,username"
      safe: "Test"
      address: "cyberark.local"
      username: "administrator-x"
      platform_id: WinServerLocal
      secret: "@N&Ibl3!"
      platform_account_properties:
          LogonDomain: "cyberark"
          OwnerName: "ansible_user"
      secret_management:
          automatic_management_enabled: true
      state: present
      cyberark_session: "{{ cyberark_session }}"
    register: cyberarkaction

  - name:
      - Rotate credential via reconcile and providing the password to
        bechanged to.
    cyberark_account:
      identified_by: "address,username"
      safe: "Domain_Admins"
      address: "prod.cyberark.local"
      username: "admin"
      platform_id: WinDomain
      platform_account_properties:
          LogonDomain: "PROD"
      secret_management:
          new_secret: "Ama123ah12@#!Xaamdjbdkl@#112"
          management_action: "reconcile"
          automatic_management_enabled: true
      state: present
      cyberark_session: "{{ cyberark_session }}"
    register: reconcileaccount

  - name: Logoff from CyberArk Vault
    cyberark_authentication:
      state: absent
      cyberark_session: "{{ cyberark_session }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
changed
boolean
always
Identify if the playbook run resulted in a change to the account in any way.

failed
boolean
always
Whether playbook run resulted in a failure of any kind.

result
complex
success
A json dump of the resulting action.

 
address
string
successful addition and modification
The adress of the endpoint where the privileged account is located.

Sample:
dev.local
 
createdTime
integer
successful addition and modification
Timeframe calculation of the timestamp of account creation.

Sample:
1567824520
 
id
integer
successful addition and modification
Internal ObjectID for the account object identified

Sample:
25_21
 
name
string
successful addition and modification
The external ObjectID of the account

Sample:
['Operating System-WinServerLocal-cyberark.local-administrator']
 
platformAccountProperties
complex
successful addition and modification
Object containing key-value pairs to associate with the account, as defined by the account platform.

   
KEY VALUE
string
successful addition and modification
Object containing key-value pairs to associate with the account, as defined by the account platform.

Sample:
[{'LogonDomain': 'cyberark'}, {'Port': '22'}]
 
platformId
string
successful addition and modification
The PolicyID of the Platform that is to be managing the account.

Sample:
WinServerLocal
 
safeName
string
successful addition and modification
The safe in the Vault where the privileged account is to be located.

Sample:
Domain_Admins
 
secretManagement
complex
successful addition and modification
Set of parameters associated with the management of the credential.

Sample:
{'automaticManagementEnabled': {'description': ['Parameter that indicates whether the CPM will manage the password or not.'], 'returned': 'successful addition and modification', 'type': 'bool'}, 'lastModifiedTime': {'description': ['Timeframe calculation of the timestamp of account modification.'], 'returned': 'successful addition and modification', 'sample': '1567824520', 'type': 'int'}, 'manualManagementReason': {'description': None, 'returned': 'if automaticManagementEnabled is set to false', 'sample': 'This is a static account', 'type': 'str'}}
 
secretType
list / elements=string
successful addition and modification
The value that identifies what type of account it will be

Sample:
['key', 'password']
 
userName
string
successful addition and modification
The username associated with the account

Sample:
administrator
status_code
integer
success
Result HTTP Status code.

Sample:
200, 201, -1, 204


Authors

  • CyberArk BizDev (@cyberark-bizdev)

  • Edward Nunez (@enunez-cyberark)

  • James Stutes (@jimmyjamcabd)