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, 104 insertions, 0 deletions

diff --git a/ansible_collections/cyberark/pas/docs/cyberark_authentication.md b/ansible_collections/cyberark/pas/docs/cyberark_authentication.md
new file mode 100644
index 000000000..7ea60d591
--- /dev/null
+++ b/ansible_collections/cyberark/pas/docs/cyberark_authentication.md
@@ -0,0 +1,104 @@
+# cyberark_authentication
+
+
+Authenticates to CyberArk Vault using Privileged Account Security Web Services SDK and creates a session fact that can be used by other modules. It returns an Ansible fact called `cyberark_session`. Every module can use this fact as `cyberark_session` parameter.
+
+
+#### Available Fields
+```
+options:
+    state:
+        default: present
+        choices: [present, absent]
+        description:
+            - Specifies if an authentication logon/logoff and a cyberark_session should be added/removed.
+    username:
+        description:
+            - The name of the user who will logon to the Vault.
+    password:
+        description:
+            - The password of the user.
+    new_password:
+        description:
+            - The new password of the user. This parameter is optional, and enables you to change a password.
+    api_base_url:
+        description:
+            - A string containing the base URL of the server hosting CyberArk's Privileged Account Security Web Services SDK.
+    validate_certs:
+        type: bool
+        default: 'true'
+        description:
+            - If C(false), SSL certificates will not be validated.  This should only
+              set to C(false) used on personally controlled sites using self-signed
+              certificates.
+    use_shared_logon_authentication:
+        type: bool
+        default: 'false'
+        description:
+            - Whether or not Shared Logon Authentication will be used.
+    use_radius_authentication:
+        type: bool
+        default: 'false'
+        description:
+            - Whether or not users will be authenticated via a RADIUS server. Valid values are true/false.
+    cyberark_session:
+        description:
+            - Dictionary set by a CyberArk authentication containing the different values to perform actions on a logged-on CyberArk session.
+    timeout:
+        type: int
+        default: 10
+        description:
+            - Allows you set a timeout for when your authenticating to Cyberark
+```
+## Example Playbooks
+
+**Shared Logon Authentication.**<br/>
+Shared authentication is based on a user credential file that is stored in the PVWA web server. During shared authentication, only the user defined in the credential file can log on to the PVWA, but multiple users can use the logon token.
+
+This type of authentication requires the playbook to manage the users as the Vault can't identify which specific user performs each action.
+
+Multiple concurrent connections can be created using the same token, without affecting each other.
+
+The shared user is defined in a user credential file, whose location is specified in the WSCredentialFile parameter, in the appsettings section of the PVWAweb.config file:
+
+```xml
+<add key="WSCredentialFile" value="C:\CyberArk\Password Vault Web Access\CredFiles\WSUser.ini"/>
+```
+> Make sure that this user can access the PVWA interface.<br/>
+> Make sure the user only has the permissions in the Vault that they require.
+
+It is recommended to secure connections between Ansible and the REST Web Services when using Shared Logon Authentication, using Client Authentication.
+
+In addition to SSL, use Client Authentication to authenticate Ansible using a client certificate.
+
+[Configuring client authentication via certificates](https://docs.cyberark.com/Product-Doc/OnlineHelp/PAS/Latest/en/Content/SDK/Configuring%20Client%20Authentication%20via%20Client%20Certificates.htm)
+
+```yaml
+- name: Logon to CyberArk Vault using PAS Web Services SDK - use_shared_logon_authentication
+  cyberark_authentication:
+    api_base_url: "{{ web_services_base_url }}"
+    use_shared_logon_authentication: true
+```
+
+**CyberArk Authentication**<br/>
+This method authenticates a user to the Vault and returns a token that can be used in subsequent web services calls. In addition, this method allows you to set a new password.
+
+Users can authenticate using **CyberArk**, **LDAP** or **RADIUS** authentication.
+
+```yaml
+- name: Logon to CyberArk Vault using PAS Web Services SDK - Not use_shared_logon_authentication
+  cyberark_authentication:
+    api_base_url: "{{ web_services_base_url }}"
+    username: "{{ password_object.password }}"
+    password: "{{ password_object.passprops.username }}"
+    use_shared_logon_authentication: false
+```
+**Logoff**<br/>
+This method logs off the user and removes the Vault session.
+
+```yaml
+- name: Logoff from CyberArk Vault
+  cyberark_authentication:
+    state: absent
+    cyberark_session: "{{ cyberark_session }}
+```