redhat_cloudforms_azure_arm_ansible/ansible-ad-group-add/README.md

# Usage

  

Should be run from a Cloudforms tile with parameters passed on runtime, there should be no need to edit the variables main.yml.

  

Cloudforms tiles pass the following mandatory parameters:

  

groupmembers="user" / "user1,user2,userN"

group=ad-group

perform=create / delete

ad_host=fqdn-of-ad-server

ad_user="user" / "user@DOMAIN.COM"

ad_pass="account-password"

from_email=donotreply@nottingham.ac.uk

api_user=cloudforms-user-with-api-write

api_pass=cloudforms-user-pass

  

- ad_pass / api_pass should have value in quotes to allow any special characters, all parameter accept quoted

- ad_user must have sufficient rights to administer group and query user object properties

- email_requester passed by cloudforms using API

- from_email address should be allowed through relay whitelist

  

More parameters can be passed, check vars/main.yml for all functional parameters, these include an output toggle, winrm connectivity and email toggles.

  

It is not recommended to hard code sensitive parameters such as passwords in the playbook vars/main.yml, these should be stored in Cloudforms which encrypts these in the database.

  

## Failure conditions

  

Any items in vars/main.yml that have the value placeholder that are not passed as parameters on runtime will fail the playbook.

  

Invalid users that are not in ActiveDirectory.

  

Connectivity issues with ActiveDirectory or SMTP relay. Ansible module error output will be observed in these scenarios.

  

## Note

  

Parameters can be passed in any order.

  

The groupmembers field will validate only populated comma delimited entries, the following will be accepted:

  

",,,tseed,,swright,,"

  

ActiveDirectory user objects have associated email addresses pulled from their published properties. Job updates will be sent to these email accounts.

  

Failure emails where ActiveDirectory users are invalid are only sent to the requester.

  

## Example command to run playbook on the command line

  

ansible-playbook adgroup.yml -e 'groupmembers="tseed,swright" \

group=Project \

perform=delete \

ad_host=WIN-1JE0R5GCBSG.NETAPPSIM.LOCAL \

ad_user="administrator@NETAPPSIM.LOCAL" \

ad_pass="Password0" \

from_email=tseed@ocf.co.uk \

enable_requester_email=false \

enable_customer_email=false \

api_user=dummy \

api_pass=dummy'

  

## Example command to run playbook on the command line and send emails with custom customer email templates

  

ansible-playbook adgroup.yml -e 'groupmembers="tseed,swright" \

group=Project \

perform=delete \

ad_host=WIN-1JE0R5GCBSG.NETAPPSIM.LOCAL \

ad_user=administrator \

ad_pass="Password0" \

from_email="noreply@cloudforms" \

enable_requester_email=true \

enable_customer_email=true \

smtp_relay=192.168.101.240 \

smtp_port=25 \

template_prefix=transcription \

requester_email=tseed@ocf.co.uk \

api_user=dummy \

api_pass=dummy '

  

## Self service mode

  

The initial design of the script catered for user(s) being added to a group and the requester getting status emails for add/remove/invalid-user/no-change operations and the users to receive add/remove emails.

  

An updated use case where the requester user populates the groupmembers parameter only with its own username is known as the self service model.

This model effectively disables the requester status emails and will send add/remove/no-change user emails to the requester.

  

To replicate this behaviour on the command line ensure the following parameter is passed with the above example syntax, and ensure the groupmember parameter only has a single user account entry.

  

groupmembers="tseed"

spoof_self_service=true

  

## Email behaviour

When template_prefix is omitted the value is set to default and default email templates used, in this scenario customer emails are not sent disregarding the parameter enable_customer_email.

To add service specific emails, create a new directory under the templates directory, populate email templates and pass matching parameter template_prefix=<my_new_service>.

Requester email templates are prefixed mail-, customer email templates customer-, there are 4 conditions in which templates are suffixed - add / remove / invalid / nochange.

Name the email templates in accordance with this convention, e.g mail-add.j2.

Customers will receive an add / remove / no-change email only when an action has been performed upon their account, customer emails are in html format.

Cloudforms local accounts such as admin do not have an email address, to debug with said accounts add parameter requester_email=<your uon email>