Adding upstream version 7.7.0+dfsg.upstream/7.7.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 278 insertions, 0 deletions

diff --git a/ansible_collections/cyberark/pas/docs/cyberark_account.md b/ansible_collections/cyberark/pas/docs/cyberark_account.md
new file mode 100644
index 000000000..7ddb4e4d5
--- /dev/null
+++ b/ansible_collections/cyberark/pas/docs/cyberark_account.md
@@ -0,0 +1,278 @@
+# cyberark_account
+
+Allows for adding, deleting, modifying a privileged credential within the Cyberark Vault.  The request uses the Privileged Account Security Web Services SDK.<br>
+
+The ability to modify consists of the following:
+
+* Password (see secret_management)
+* Safe
+* Platform
+* Address
+* Object Name
+* Username
+* Platform Account Properties
+  * These are the parameters listed in the Platform under `UI & Workflows -> Properties` and are unique to each Platform (see image below)
+* Remote Machines Access
+
+![Platform Account Properties](https://github.com/cyberark/ansible-security-automation-collection/blob/master/docs/images/platform_account_properties.JPG?raw=true)
+
+### secret_management
+The `secret_management` dictionary provides the capability to set a CPM password rotation flag on an existing account.
+
+The available options are as follows:<br>
+
+`automatic_management_enabled`: bool<br>
+`manual_management_reason`: This is a string value that populates the Reason field is you have set an account to not be managed by the CPM.  This value is only necessary if `automatic_management_enabled` is set to false.<br>
+`management_action`: This value indicates what type CPM management flag will be placed on the account
+* change - <br>
+* change_immediately - <br>
+* reconcile - <br>
+
+`new_secret`: This parameter is available to set the value of the new password<br>
+`perform_secret_management`: This parameter was allows the option to place a CPM management flag on an account upon creation of an account object.
+* always - All `secret_management` actions will follow the table below at all times.
+* on_create - Will place a CPM management flag according to the table below ONLY on creation of an account object.
+
+#### Secret Management Action Table
+| management_action   | new_secret  | Action  |
+| :---------: | :----: | :----- |
+| change | populated | change password to set value at next scheduled rotation |
+| change | NULL | rotate password at next scheduled rotation |
+| change_immediately | populated | change immediately to the set value |
+| change_immediately | NULL | rotate immediately |
+| reconcile | populated | reconcile immediately NOT to set value |
+| reconcile | NULL | reconcile immediately |
+| NULL | populated | set value in Vault ONLY |
+
+
+### identified_by
+This property allows for the module to confidently identify the account object needing to be identified.  If multiple accounts are returned from the modules initial `Get Accounts` it will use the value(s) set in the `identified_by` parameter to direct which account is selected from the list.
+
+**EXAMPLE:**
+```
+-Playbook Parameters-
+
+cyberark_account:
+  identified_by: "address,username,platform_id"
+  safe: "testSafe"
+  address: "dev.local"
+  username: "admin"
+  platform_id: WinDomain
+
+  -This is the query sent to CyberArk Web SDK:
+/api/Accounts?filter=safeName eq testSafe&search= admin dev.local
+
+**This could return multiple accounts in the testSafe**
+
+RETURNED:
+account1
+  username: administrator
+  address: cyberark.dev.local
+  safe: testSafe
+  policyID: WinDomain
+
+account2
+  username: admin
+  address: dev.local
+  safe: testSafe
+  policyID: WinDomain
+```
+With the `identified_by` parameter set the `cyberark_account` module will select the account2 object becauses the values of the `address`, `username` and `platform_id` parameters are identical matches to the values of account2 properties.
+
+#### Limitations
+**Idempotency** - All actions taken in the module adhere to the Ansible idempotency guidelines _except_ for password change.  If you have the playbook set to modify a password it will send a password change request every time the playbook is run, even if you are defining the next password value and it is the same password that is set in other runs.<br>
+**Remote Machines Access** - When modifying the values in the `remote_machines_access` dictionary be mindful of the `platform_id` value.  Remote Machines Access values are stored at the Vault database level and not stored as File Categories.  It is a function that is only available with the `WinDomain` platform and if you attempt to assign these values to another platform it will cause errors in the PSM functionality.
+
+
+#### Available Fields
+```
+options:
+    state:
+        description:
+            - Assert the desired state of the account C(present) to creat or update and account object. Set to C(absent) for deletion of an account object
+        required: true
+        default: present
+        choices: [present, absent]
+        type: str
+    logging_level:
+        description:
+            - Parameter used to define the level of troubleshooting output to the C(logging_file) value
+        required: true
+        choices: [NOTSET, DEBUG, INFO]
+        type: str
+    logging_file:
+        description:
+            - Setting the log file name and location for troubleshooting logs
+        required: false
+        default: /tmp/ansible_cyberark.log
+        type: str
+    api_base_url:
+        description:
+            - A string containing the base URL of the server hosting CyberArk's Privileged Account Security Web Services SDK
+            - Example: U(https://<IIS_Server_Ip>/PasswordVault/api/)
+        required: true
+        type: str
+    validate_certs:
+        description:
+            - If C(false), SSL certificate chain will not be validated.  This should only set to C(true) if you have a root CA certificate installed on each node.
+        required: false
+        default: true
+        type: bool
+    cyberark_session:
+        description:
+            - Dictionary set by a CyberArk authentication containing the different values to perform actions on a logged-on CyberArk session, please see M(cyberark_authentication) module for an example of cyberark_session.
+        required: true
+        type: dict
+    identified_by: 
+        description:
+            - 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.
+        required: false
+        default: username,address,platform_id
+        type: str        
+    safe:
+        description:
+            - The safe in the Vault where the privileged account is to be located
+        required: true
+        type: str
+    platform_id:
+        description:
+            - The PolicyID of the Platform that is to be managing the account
+        required: false
+        type: str
+    address:
+        description:
+            - The adress of the endpoint where the privileged account is located
+        required: false
+        type: str
+    name:
+        description:
+            - The ObjectID of the account
+        required: false
+        type: str
+    secret_type:
+        description:
+            - The value that identifies what type of account it will be.
+        required: false
+        default: password
+        choices: [password, key]
+        type: str
+    secret:
+        description:
+            - The initial password for the creation of the account
+        required: false
+        type: str
+    username:
+        description:
+            - The username associated with the account
+        required: false
+        type: str
+    secret_management
+        description:
+            - Set of parameters associated with the management of the credential
+        required: false
+            suboptions:
+                automatic_management_enabled:
+                    description:
+                        - Parameter that indicates whether the CPM will manage the password or not
+                    default: true
+                    type: bool
+                manual_management_reason:
+                    description:
+                        - String value indicating why the CPM will NOT manage the password
+                    type: str
+                management_action:
+                    description:
+                        - CPM action flag to be placed on the account object for credential rotation
+                    choices: [change, change_immediately, reconcile]
+                    type: str
+                new_secret:
+                    description:
+                        - The actual password value that will be assigned for the CPM action to be taken
+                    type: str
+                perform_management_action:
+                    description:
+                        - C(always) will perform the management action in every action
+                        - C(on_create) will only perform the management action right after the account is created
+                    choices: [always, on_create]
+                    default: always
+                    type: str
+    remote_machines_access:
+        description:
+            - Set of parameters for defining PSM endpoint access targets
+        required: false
+        type: dict
+            suboptions:
+                remote_machines:
+                    description:
+                        - List of targets allowed for this account 
+                    type: str
+                access_restricted_to_remote_machines:
+                    description:
+                        - Whether or not to restrict access only to specified remote machines
+                    type: bool
+    platform_account_properties:
+        description:
+            - 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.
+        required: false
+        type: dict
+            suboptions:
+                KEY:
+                    description:
+                        - Freeform key value associated to the mandatory or optional property assigned to the specified Platform's definition.
+                    aliases: [Port, ExtrPass1Name, database]
+                    type: str
+```
+
+## Example Playbooks
+
+
+```yaml
+  tasks:
+
+    - name: Logon to CyberArk Vault using PAS Web Services SDK
+      cyberark.pas.cyberark_authentication:
+        api_base_url: "http://components.cyberark.local"
+        validate_certs: false
+        username: "bizdev"
+        password: "Cyberark1"
+
+    - name: Creating an Account using the PAS WebServices SDK
+      cyberark.pas.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 be changed to
+      cyberark.pas.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.pas.cyberark_authentication:
+        state: absent
+        cyberark_session: "{{ cyberark_session }}"
+```