Modify Users in Security Group

This is an interactive task for adding & removing Users to & from an Active Directory Security Group.

This task only modifies direct group memberships, not nested memberships.

Playbook Files

This playbook was built for PPA version 3.3

plugins:
  active_directory: ^13.0
  hashicorp_vault: ^8.0
  ppa: ^11.4

set:
  search_base: null
  cancel_add: false
  cancel_remove: false

steps:

  - name: Greeting

    actions:
      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.active_directory.full }}


            #### Active Directory - Amend Group Memberships


            Use this task to modify the user memberships for a Security Group in Active Directory.


            You will need to:


            - Search for the Security Group

            - Choose the operations to perform (add users, remove users, or both)

            - Pick the users for each operation accordingly


            __Note:__ This task only operates on users _directly_ in the chosen Security Group.

      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: active_directory
          keys:
            - name: address
            - name: domain
            - name: username
            - name: password
              sensitive: true
          reason: Getting Active Directory details
          create_missing: true
        save: domain_controller


  - name: Select Group
    actions:

      - active_directory.groups.get_interactive:
        load:
          domain_controller: domain_controller
        save: active_directory_group


  - name: Select Operation(s)
    actions:

      - ppa.ui.input_choice:
          text: Please choose an option
          options:
            - value: Add Users
              order: 1
            - value: Remove Users
              order: 2
            - value: Add & Remove Users
              order: 3
        save: operation


  - name: Get Users
    when: operation in ['Add Users', 'Add & Remove Users']
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Add Users


            PPA will audit users from Active Directory & ask you to make a selection.


            You can narrow the audit down to an Organizational Unit if required.

      - ppa.ui.input_accept:
          text: OK

      - ppa.ui.input_confirm:
          text: Please choose an option
          confirm: Choose Organizational Unit
          cancel: Get All Users
        save: choose_ou

      - active_directory.organizational_units.get_all:
        load:
          domain_controller: domain_controller
        save: organizational_units
        when: choose_ou

      - active_directory.organizational_units.select_one:
          text: Select an Organizational Unit
        load:
          organizational_units: organizational_units
        save: organizational_unit
        when: choose_ou

      - set:
          name: search_base
          value: '{{ organizational_unit.distinguishedName }}'
        when: choose_ou

      - ppa.ui.output_progress:
          text: Getting users from Active Directory...
          percent: null
          element_id: getting_users

      - active_directory.users.get_all:
        load:
          search_base: search_base
          domain_controller: domain_controller
        save: users

      - ppa.ui.output_progress:
          text: Got {{ users | length }} users from Active Directory
          percent: 100
          element_id: getting_users


  - name: Select Users To Add
    when: operation in ['Add Users', 'Add & Remove Users']
    while:
      name: add_step_complete
      value: false
    actions:

      - active_directory.users.select:
          text: Select users to add
        load:
          users: users
        save: add_selection

      - ppa.ui.output_error:
          text: No users were selected.
        when: add_selection.total == 0

      - ppa.ui.input_confirm:
          text: Cancel the operation?
        save: cancel
        when: add_selection.total == 0

      - set:
          name: cancel_add
          value: true
        when: add_selection.total == 0 and cancel

      - set:
          name: add_step_complete
          value: true
        when: add_selection.total == 0 and cancel

      - active_directory.users.display:
          text: Selected users
        load:
          users: add_selection.all
        when: add_selection.total > 0

      - ppa.ui.input_confirm:
          text: Add these users to the group?
        save: add_step_complete
        when: add_selection.total > 0

      - ppa.ui.output_error:
          text: Please select the users again.
        when: not add_step_complete or cancel_add


  - name: Add Users To Group
    when: operation in ['Add Users', 'Add & Remove Users'] and not cancel_add
    actions:

      - ppa.ui.output_progress:
          text: Adding {{ add_selection.total }} users to {{ active_directory_group.cn }}...
          percent: null
          element_id: adding_users

      - active_directory.users.add_to_group:
        load:
          user_distinguishedName: user.distinguishedName
          group_distinguishedName: active_directory_group.distinguishedName
          domain_controller: domain_controller
        for_each:
          items: add_selection.all
          name: user

      - ppa.ui.output_progress:
          text: Added {{ add_selection.total }} users to {{ active_directory_group.cn }}
          percent: 100
          element_id: adding_users


  - name: Get Users In Group
    when: operation in ['Remove Users', 'Add & Remove Users']
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Remove Users


            PPA will now audit users directly in the group.


            You will then be asked to select users to remove.

      - ppa.ui.input_accept:
          text: OK

      - ppa.ui.output_progress:
          text: Getting users from {{ active_directory_group.cn }}...
          percent: null
          element_id: getting_user_members

      - active_directory.groups.get_users:
          nested: false
        load:
          distinguishedName: active_directory_group.distinguishedName
          domain_controller: domain_controller
        save: user_members

      - ppa.ui.output_progress:
          text: Got {{ user_members | length }} users from {{ active_directory_group.cn }}
          percent: 100
          element_id: getting_user_members


  - name: Select Users To Remove
    when: operation in ['Remove Users', 'Add & Remove Users']
    while:
      name: remove_step_complete
      value: false
    actions:

      - active_directory.users.select:
          text: Select users to remove
        load:
          users: user_members
        save: remove_selection

      - ppa.ui.output_error:
          text: No users were selected.
        when: remove_selection.total == 0

      - ppa.ui.input_confirm:
          text: Cancel the operation?
        save: cancel
        when: remove_selection.total == 0

      - set:
          name: cancel_remove
          value: true
        when: remove_selection.total == 0 and cancel

      - set:
          name: remove_step_complete
          value: true
        when: remove_selection.total == 0 and cancel

      - active_directory.users.display:
          text: Selected users
        load:
          users: remove_selection.all
        when: remove_selection.total > 0

      - ppa.ui.input_confirm:
          text: Remove these users from the group?
        save: remove_step_complete
        when: remove_selection.total > 0

      - ppa.ui.output_error:
          text: Please select the users again.
        when: not remove_step_complete or cancel_remove


  - name: Remove Users From Group
    when: operation in ['Remove Users', 'Add & Remove Users'] and not cancel_remove
    actions:

      - ppa.ui.output_progress:
          text: Removing {{ remove_selection.total }} users from {{ active_directory_group.cn }}...
          percent: null
          element_id: removing_users

      - active_directory.users.remove_from_group:
        load:
          user_distinguishedName: user.distinguishedName
          group_distinguishedName: active_directory_group.distinguishedName
          domain_controller: domain_controller
        for_each:
          items: remove_selection.all
          name: user

      - ppa.ui.output_progress:
          text: Removed {{ remove_selection.total }} users from {{ active_directory_group.cn }}
          percent: 100
          element_id: removing_users


  - name: Summary
    actions:

      - ppa.ui.output_info:
          text: All operations completed successfully!

Running this Playbook

Click download playbook
Import the playbook on the Playbooks page in PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab

Integrations

PPA User Interface
Hashicorp Vault Key-Value engine
Active Directory Users & Groups

Required Vault Details

Active Directory

IP/DNS address of a Domain Controller
Domain FQDN
Username
Password

As this is a privileged task, the Active Directory credentials require the permission to add & remove Users to & from Security Groups.

Vault Configuration Wizard

The first time you run a task built from this playbook, PPA will check the required Vault details exist.

If they don't exist, PPA will ask you to supply the details at the start of the task.

Below you can see a user providing details the first time they run an Active Directory task.

vault-config-wizard

Once the details are added to Vault, the task won't ask for them again.

If you don't know the required details, ask an administrator to run the task or configure Vault manually.

What the Task Does

Once started, this task allows the operator to:

Search for and select an Active Directory Security Group
Choose whether to add Users, remove Users, or both

See our other playbooks

Get PPA for free!

Start automating your estate with a free 30 day trial today. No signup required!

Get PPA Express

Documentation

Installation Guide
See how easy it is to get started with our installation guide
Playbooks
View our task writing reference guide
Plugins
See how to integrate with different systems using our plugins reference guide.