senhasegura Ansible PAM Collection is now publicly available

senhasegura · Mar 24, 2021 · f5b73f6 · f5b73f6
1 parent 93396d1
commit f5b73f6
Show file tree

Hide file tree

Showing 15 changed files with 1,229 additions and 0 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Changelog
+
+## [1.0.0] - 2021-02-15
+
+### Added
+
+- The following modules have been added to [senhasegura-pam-collection](https://galaxy.ansible.com/senhasegura/pam)
+	- senhasegura_device
+	- senhasegura_credential
+	- senhasegura_credential_info
+
+[1.0.0]: https://github.com/senhasegura/ansible-pam-collection/tree/v1.0.0
+
diff --git a/README.md b/README.md
@@ -0,0 +1,50 @@
+![logo](https://github.com/senhasegura/ansible-pam-collection/blob/main/docs/imgs/senhasegura-logo.jpg?raw=true)
+
+
+## senhasegura Privileged Access Management Ansible Collection
+
+senhasegura PAM Ansible Collection provides ansible modules for interacting with senhasegura's PAM module
+
+Hosted in [galaxy.ansible.com/senhasegura](https://galaxy.ansible.com/senhasegura)
+
+*************
+
+### Requirements
+
+  - senhasegura with PAM module enabled
+
+---
+
+### Installation
+
+In your terminal, run the following command
+
+	ansible-galaxy collection install senhasegura.pam
+
+### Modules
+
+**senhasegura_device**
+
+With this module you can create, update and deactivate devices in senhasegura's PAM module
+
+[Detailed documentation](https://github.com/senhasegura/ansible-pam-collection/blob/main/docs/senhasegura_device.md)
+
+**senhasegura_credential**
+
+With this module you can create, update and deactivate credentials in senhasegura's PAM module
+
+[Detailed documentation](https://github.com/senhasegura/ansible-pam-collection/blob/main/docs/senhasegura_credential.md)
+
+**senhasegura_credential_info**
+
+With this module you can get informations about a credential, including your password
+
+[Detailed documentation](https://github.com/senhasegura/ansible-pam-collection/blob/main/docs/senhasegura_credential_info.md)
+
+---
+
+## Author information
+
+- Lucas Fraga (@lfraga)
+- James Miranda (@jameswpm)
+
diff --git a/docs/Tower-injector-configuration.yaml b/docs/Tower-injector-configuration.yaml
@@ -0,0 +1,4 @@
+env:
+  SENHASEGURA_CLIENT_ID: '{{ senhasegura_client_id }}'
+  SENHASEGURA_CLIENT_SECRET: '{{ senhasegura_client_secret }}'
+  SENHASEGURA_URL: '{{ senhasegura_url }}'
diff --git a/docs/Tower-input-configuration.yaml b/docs/Tower-input-configuration.yaml
@@ -0,0 +1,16 @@
+fields:
+  - id: senhasegura_url
+    type: string
+    label: senhasegura URL
+  - id: senhasegura_client_id
+    type: string
+    label: Client ID
+    secret: true
+  - id: senhasegura_client_secret
+    type: string
+    label: Client Secret
+    secret: true
+required:
+  - senhasegura_url
+  - senhasegura_client_id
+  - senhasegura_client_secret  
diff --git a/docs/Tower-users.md b/docs/Tower-users.md
@@ -0,0 +1,27 @@
+## Using senhasegura Privileged Access Management Ansible Collection with Ansible Tower
+
+We recomends creating an "Custom Credential Type" to store senhasegura OAuth2 tokens used by modules
+
+---
+
+### Installation
+
+In your Ansible Tower instance, logged with administrator user
+
+1. Click on Credential Types option in menu, under Administration section
+2. Click the green button to add new Custom Credential Type
+3. Set the name of your custom credential type, e.g "senhasegura A2A"
+4. Optionally set an description, e.g "senhasegura for Ansible AWX"
+5. Under "Input Configuration" select "YAML" format and paste content in file Tower-input-configuration.yaml
+6. Under "Injector Configuration" select "YAML" format and paste content in file Tower-injector-configuration.yaml
+
+---
+
+### Usage
+
+1. Create a credential using the Custom Credential Type generated above and place the OAuth2 tokens generated by senhasegura
+
+2. Link the credential with the desired Job Template
+
+3. Run Job Template
+
diff --git a/docs/imgs/senhasegura-logo.jpg b/docs/imgs/senhasegura-logo.jpg
diff --git a/docs/senhasegura_credential.md b/docs/senhasegura_credential.md
@@ -0,0 +1,136 @@
+## senhasegura_credential
+
+This module can be used to create, update and deactivate credentials in senhasegura's PAM module
+
+---
+
+### Example PlayBooks
+
+Ensure credential 'ansible' in device 'linux-001'
+
+```yaml
+- name: Ensure credential 'ansible' in device 'linux-001'
+  senhasegura.pam.senhasegura_credential:
+    state: present
+    identifier: ansible-usr-linux-001
+    device_hostname: linux-001
+    type: Local user
+    username: ansible
+    password: your_secret_password
+    tags:
+      - ansible
+      - automation
+    additional_info: 'Credential created by Ansible'
+```
+
+Domain user CORP\bob creation in senhasegura
+
+```yaml
+- name: Ensure domain user 'CORP\bob' in device 'windows-ad'
+  senhasegura.pam.senhasegura_credential:
+    state: present
+    identifier: your_unique_credential_identifier
+    device_hostname: windows-ad
+    type: Domain user
+    username: ansible
+    password: your_secret_password
+    domain: CORP
+    tags:
+      - domain
+      - automation
+    additional_info: 'Credential created by Ansible'
+```
+
+Deactivate credential with identifier "domain_user_alice"
+
+```yaml
+- name: Deactivate credential
+  senhasegura.pam.senhasegura_credential:
+    state: absent
+    identifier: domain_user_alice
+```
+---
+
+### Available options
+
+```
+options:
+    system_url:
+        type: str
+        description:
+            - senhasegura's environment URL used for authentication, SENHASEGURA_URL environment variable may also be used
+    client_id:
+        type: str
+        description:
+            - A2A OAuth2 client_id, SENHASEGURA_CLIENT_ID environment variable may also be used
+    client_secret:
+        type: str
+        description:
+            - A2A OAuth2 client_secret, SENHASEGURA_CLIENT_SECRET environment variable may also be used
+    state:
+        description:
+            - Whether the credential should exist or not,
+        type: str
+        choices: [ absent, present ]
+        default: present
+    identifier:
+        required: true
+        type: str
+        description:
+            - credential identifier for management
+    device_hostname:
+        type: str
+        description:
+            - Device hostname to link credential
+            - Required when state is present
+    device_address:
+        type: str
+        description:
+            - Device address to link credential
+            - Required when state is present
+    type:
+        description:
+            - Type of credential
+            - Required when state is present
+        type: str
+        choices: [ Local User, Local administrator, Domain user ]
+        default: Local User
+    username:
+        type: str
+        description:
+            - Credential username
+            - Required when state is present
+    password:
+        description:
+            - Credential password
+            - This password must meet the password policy requirements
+        type: str
+    domain:
+        description:
+            - Domain name, It needs to be previously registered in senhasegura
+        type: str
+    tags:
+        description:
+            - Credential tags
+        type: list
+    additional_info:
+        description:
+            - Credential additional information
+        type: str
+    parent_credential:
+        description:
+            - Parent credential numeric identifier
+        type: int
+    validate_certs:
+        description:
+            - Whether to validate or not the HTTPS certificate
+        type: boolean
+```
+
+---
+
+Full module docummentation is available using `ansible-doc` after collection install
+
+    $ ansible-galaxy collection install senhasegura.pam
+    $ ansible-doc --type module senhasegura.pam.senhasegura_credential
+
diff --git a/docs/senhasegura_credential_info.md b/docs/senhasegura_credential_info.md
@@ -0,0 +1,65 @@
+## senhasegura_credential_info
+
+This module can be used to get credentials information and secret strings a.k.a passwords
+
+---
+
+### Example PlayBooks
+
+
+Get credential by identifier
+
+```yaml
+- name: Get credential with identifier 'ansible
+  senhasegura.pam.senhasegura_credential_info:
+    identifier: your_credential_identifier
+  register: senhasegura_credential
+```
+
+Get credential by ID
+```yaml
+- name: Get credential with identifier 'ansible
+  senhasegura.pam.senhasegura_credential_info:
+    id_credential: 1582
+  register: senhasegura_credential
+```
+
+---
+
+### Available options
+
+```
+options:
+    system_url:
+        type: str
+        description:
+            - senhasegura's environment URL used for authentication, SENHASEGURA_URL environment variable may also be used
+    client_id:
+        type: str
+        description:
+            - A2A OAuth2 client_id, SENHASEGURA_CLIENT_ID environment variable may also be used
+    client_secret:
+        type: str
+        description:
+            - A2A OAuth2 client_secret, SENHASEGURA_CLIENT_SECRET environment variable may also be used
+    identifier:
+        type: str
+        description:
+            - The credential identifier to get information
+    id_credential:
+        type: str
+        description:
+            - The credential ID to get information
+    validate_certs:
+        description:
+            - Whether to validate or not the HTTPS certificate
+        type: bool
+```
+
+---
+
+Full module docummentation is available using `ansible-doc` after collection install
+
+    $ ansible-galaxy collection install senhasegura.pam
+    $ ansible-doc --type module senhasegura.pam.senhasegura_credential_info
+