Recertify Group Members

This is an interactive task that allows the operator to recertify the users with direct memberships to Active Directory groups they manage.

The managedBy Active Directory group attribute is used to establish the groups managed by the operator.

Users are selected/unselected from a table to either certify or decertify their memberships.

Playbook Files

This playbook was built for PPA version 3.0.x

# The task was built to work with these plugin versions.
plugins:
  active_directory: ^12.1
  hashicorp_vault: ^7.1
  ppa: ^10.0
  ppa_tools: ^10.4


set:
  remove: false  # Set to true to remove unselected users from the groups.
  removal_list: []  # This is maintained by the task.
  removal_tables: []  # This is maintained by the task.


steps:

  - name: Get PPA User Info
    actions:

      - user_info:
        save: ppa_user


  - name: Exit If Not Domain User
    when: not ppa_user.domain
    actions:

      - ppa.ui.output_error:
          text: This task can only be run by a domain user account.

      - exit:
          exit_code: 2


  - name: Greeting
    actions:

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


            #### Active Directory - Recertify Group Members


            Use this task to recertify users in Active Directory groups.


            You will be asked to do the following for each _group you manage_:


            - Certify users by _selecting_ them

            - Decertify users by leaving them _unselected_

            - Confirm your selection


            Once all groups have been reviewed, you will be asked for an email address to send the report to.


            __Note:__ PPA {{'__will remove__' if remove == True else '__will not remove__' }} unselected users from the groups.



      - ppa.ui.input_accept:
          text: Start


  - name: Get Active Directory 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: Find PPA User in Active Directory
    actions:

      - ppa.ui.output_progress:
          text: Finding your Active Directory user account...
          percent: null
          element_id: finding_ppa_user

      - active_directory.users.by_samaccountname:
        load:
          sAMAccountName: ppa_user.username
          domain_controller: domain_controller
        rescue:

          - ppa.ui.output_progress:
              text: Failed to find your Active Directory user account
              percent: 0
              element_id: finding_ppa_user

          - ppa.ui.output_error:
              text: "PPA couldn't find your user account on {{ domain_controller.domain }}."
            when: >
              "No user found" in rescue.error

          - exit:
              exit_code: 3
            when: >
              "No user found" in rescue.error

          - ppa.ui.output_error:
              text: "An error occurred while searching for your user account on {{ domain_controller.domain }}. Please view the logs for more information."

          - exit:
              exit_code: 4
        save: ppa_domain_user

      - ppa.ui.output_progress:
          text: Found your Active Directory user account
          percent: 100
          element_id: finding_ppa_user


  - name: Find Groups Owned by PPA User
    actions:

      - ppa.ui.output_progress:
          text: Finding Active Directory groups managed by you...
          percent: null
          element_id: finding_managed_groups

      - active_directory.groups.search:
          search_params:
            managedBy: "{{ ppa_domain_user.distinguishedName }}"
        load:
          domain_controller: domain_controller
        save: managed_groups

      - ppa.ui.output_progress:
          text: Found {{ managed_groups.total }} Active Directory groups managed by you
          percent: 100
          element_id: finding_managed_groups


  - name: Exit If No groups
    when: managed_groups.total == 0
    actions:

        - ppa.ui.output_info:
            text: You are not the manager of any groups in Active Directory.

        - ppa.ui.input_accept:
            text: OK

        - exit:
            exit_code: 0


  - name: Select Groups
    actions:

      - active_directory.groups.select:
          text: Select Groups to Review
        load:
          groups: managed_groups.all
        save: group_selection


  - name: Exit If No Groups Selected
    when: group_selection.total == 0
    actions:

      - ppa.ui.output_info:
          text: No groups were selected, goodbye!

      - exit:
          exit_code: 0


  - name: Recertify Group Memberships
    for_each:
      items: group_selection.all
      name: group
    actions:

      - active_directory.groups.review_users:
        load:
          remove: remove  # This is configured in the set section.
          distinguishedName: group.distinguishedName
          domain_controller: domain_controller
        save: review_results

      - count:
        load:
          item: review_results.users_to_remove
        save: remove_count

      - ppa_tools.dictionaries.create:
        load:
          group: group
          users_to_remove: review_results.users_to_remove
        save: current_group_review
        when: remove_count > 0

      - ppa_tools.lists.append:
        load:
          items: removal_list
          value: current_group_review
        save: removal_list
        when: remove_count > 0

      - ppa.ui.input_accept:
          text: Next Group
        when: step_counter < group_selection.total


  - name: Exit If No Removals
    when: not removal_list
    actions:

      - ppa.ui.output_info:
          text: No users have been decertified from any groups. Goodbye!

      - exit:
          exit_code: 0


  - name: Generate Group Removal Tables
    for_each:
      items: removal_list
      name: group
    actions:

      - ppa.ui.output_progress:
          text: Generating the certification report...
          percent: null
          element_id: generating_report

      - ppa_tools.generate.table_from_dictionaries:
          header:
            - Common Name
            - Email Address
          keys:
            - cn
            - mail
        load:
          dictionaries: group.users_to_remove
        save: current_group_table

      - ppa_tools.generate.html_table:
        load:
          header: current_group_table.header
          rows: current_group_table.rows
        save: current_group_html_table

      - ppa_tools.files.read_text_file:
          name: removal_table.html
        save: removal_table

      - format_template:
          key_values:
            group_name: "{{ group.group.cn }}"
            removal_table: "{{ current_group_html_table }}"
        load:
          template: removal_table
        save: formatted_table

      - ppa_tools.lists.append:
        load:
          items: removal_tables
          value: formatted_table
        save: removal_tables

      - ppa.ui.output_progress:
          text: Generated the certification report
          percent: 100
          element_id: generating_report


  - name: Send Email Report
    actions:

      - ppa_tools.files.read_text_file:
          name: email.html
        save: email

      - format_template:
          key_values:
            icon: "{{ globals.icons.ppa.full }}"
            group_manager: "{{ ppa_user.username }}"
            removal_hint: "{{ 'were' if remove == True else 'should be' }}"
            removal_table: "{{ removal_tables | join('\n\n') }}"
        load:
          template: email
        save: formatted_email

      - ppa.ui.input_email:
          text: Please supply an email address for reporting
        save: recipient

      - ppa.ui.output_progress:
          text: Sending report email...
          percent: null
          element_id: sending_report

      - ppa.events.send_email:
          subject: PPA - Active Directory Certification
          reason: Sending certification report email
          recipients:
            - "{{ recipient }}"
        load:
          html: formatted_email
        rescue:

          - ppa.ui.output_progress:
              text: Failed to send report email
              percent: 0
              element_id: sending_report

          - ppa.ui.output_error:
              text: Failed to send email report. SMTP is not configured in PPA.
            when: rescue.type == "EventNotConfigured"

          - exit:
              exit_code: 2
            when: rescue.type == "EventNotConfigured"

          - ppa.ui.output_error:
              text: Failed to send email report. Please view the logs for more information.

          - exit:
              exit_code: 3

      - ppa.ui.output_progress:
          text: Sent report email
          percent: 100
          element_id: sending_report

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

Running Modes

The task can run in 2 modes:

Reporting Mode (default)

The task will not remove decertified users.

A report email is sent at the end of the task.

Active Mode

The task will remove decertified users.

A report email is sent at the end of the task.

Changing Mode

You can switch between running modes by changing the value of remove on line 10.

Integrations

PPA User Interface & Events
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 task can be configured to modify group memberships, the Active Directory credentials may require write permissions.

If you only run this task in Reporting Mode, only read permissions are required.

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:

Select one or more groups managed by them
Recertify users with a direct membership to each selected group
Select or unselect users in a table to certify/decertify their memberships

If the task is running in Active Mode (see Running Modes above), unselected users will be removed from the relevant groups.

Once all groups have been reviewed, the operator should supply an email address that PPA will send a report to.

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.