View a Group's User Memberships

This is an interactive task for auditing the users in an Active Directory group.

It is a read-only task that doesn't require a privileged account on Active Directory.

Playbook Files

# The task was built to work with these plugin versions.
plugins:
  ppa: ~5
  ppa_tools: ~5
  hashicorp_vault: ~5
  active_directory: ~7


set:
  # This gets a default value in case the user chooses direct memberships only.
  nested_members: []


steps:

  - name: Greeting
    actions:

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

            #### Active Directory - View Users in a Group


            Use this task to view the direct or complete user memberships for an Active Directory group.


            You will need to:


            - Search for and select the Active Directory group.


            - Choose whether to get **direct** or **all** users.


            You can export the memberships report CSV file when the table is displayed.


            ___Important___: getting **all** members can be slow.

      - 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: Confirm Member Type
    actions:

      - ppa.ui.input_confirm:
          text: Show direct memberships, or all memberships?
          confirm: All
          cancel: Direct Only
        save: nested


  - name: Get Direct Group Members
    actions:

      - ppa.ui.output_progress:
          text: Getting direct group members for {{ active_directory_group.cn }}...
          percent: null
          element_id: get_direct_members

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

      - ppa.ui.output_progress:
          text: Got direct group members for {{ active_directory_group.cn }}
          percent: 100
          element_id: get_direct_members


  - name: Get Nested Group Members
    when: nested
    actions:

      - ppa.ui.output_progress:
          text: Getting nested group members for {{ active_directory_group.cn }}...
          percent: null
          element_id: get_nested_members

      - active_directory.groups.get_users:
          nested: true
        load:
          distinguishedName: active_directory_group.distinguishedName
          domain_controller: domain_controller
        save: nested_members

      - ppa.ui.output_progress:
          text: Got nested group memberships for {{ active_directory_group.cn }}
          percent: 100
          element_id: get_nested_members


  - name: Exit if No Members
    when: not direct_members and not nested_members
    actions:

      - ppa.ui.output_info:
          text: Group '{{ active_directory_group.cn }}' contains no users.

      - ppa.ui.input_accept:
          text: OK

      - exit:
          exit_code: 0


  - name: Collate Membership Data
    when: nested
    actions:

      # All groups that don't exist in direct memberships will be nested memberships.
      - ppa_tools.lists.difference:
        load:
          first: nested_members
          second: direct_members
        save: nested_members

      # All groups that don't exist in nested memberships will be direct memberships.
      - ppa_tools.lists.difference:
        load:
          first: direct_members
          second: nested_members
        save: direct_members

      # Create the "Direct Memberships" tab
      - ppa_tools.dictionaries.create:
        load:
          Direct: direct_members
          Nested: nested_members
        save: tabs

  - name: Display Results
    actions:

      - active_directory.users.display_tabbed:
          text: Direct & nested users in {{ active_directory_group.cn }}
        load:
          tabs: tabs
        when: nested

      - active_directory.users.display:
          text: Direct uses in {{ active_directory_group.cn }}
        load:
          users: direct_members
        when: not nested

      - ppa.ui.input_accept:
          text: Done

Running this Playbook

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

* Requires PPA v2.9.x or newer

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 read-only task, the Active Directory credentials do not require write permissions.

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 group
Choose whether to audit direct or all users in the group
View & download the resultant group membership table

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.