Create Security Group

This is an interactive task for creating & configuring the memberships of a new security group in Active Directory.
Playbook Files

This playbook was built for PPA version 3.3
# The task was built to work with these plugin versions.
plugins:
  ppa: ^11.4
  ppa_tools: ^11.0
  hashicorp_vault: ^8.0
  active_directory: ^13.0


steps:

  - name: Greeting
    actions:

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


            ### Active Directory - New Security Group


            Use this task to create a new security group in Active Directory.


            You will need to:


            - Provide group information


            - Choose where to create it in Active Directory


            - Set the group's manager (optional)


            - Select groups to add it to (optional)


            - Select users to add to the new group (optional)


      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

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


  - name: Get Group Details
    while:
      name: group_confirmed
      value: false
      restart: group_exists
    actions:

      - ppa.ui.input_form:
          text: New Group Details
          fields:
            - text:
                name: name
                title: Name
                required: true
            - text:
                name: display_name
                title: Display Name
                required: true
            - choice:
                name: group_type
                title: Group Type
                default: Global
                options:
                  - Global
                  - Domain Local
                  - Universal
            - text:
                name: description
                title: Description
                required: false
          element_id: group_details
        save: group_details

      - active_directory.groups.search:
          search_params:
            sAMAccountName: "{{ group_details.name }}"
        load:
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A group named '{{ group_details.name }}' already exists, please supply a different name.
          element_id: "{{ group_details.name }}_exists"
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: group_exists
          value: true
        when: search_result.total > 0

      - ppa.ui.output_markdown:
          doc: >
            ### New Group Details


            **Name:** {{ group_details.name }}


            **Display Name:** {{ group_details.display_name }}


            **Group Type:** {{ group_details.group_type }}


            **Description:** {{ group_details.description or '_not supplied_' }}

      - set:
          name: cn
        load:
          value: group_details.display_name

      - ppa.ui.input_confirm:
          text: Are these details correct?
          confirm: Yes
          cancel: No
        save: group_confirmed

      - ppa.ui.output_error:
          text: Please supply the information again.
        when: not group_confirmed


  - name: Organizational Unit Intro
    actions:

      - ppa.ui.output_progress:
          text: Getting all Organizational Units...
          element_id: getting_ous

      - active_directory.organizational_units.get_all:
        load:
          domain_controller: domain_controller
        save: all_organizational_units

      - ppa.ui.output_progress:
          text: Got all Organizational Units
          percent: 100
          element_id: getting_ous

      - ppa.ui.output_markdown:
          doc: >
            ### Group Location


            You now need to choose where to create the group in Active Directory.


            Click OK & select an Organizational Unit from the table.

      - ppa.ui.input_accept:
          text: OK


  - name: Choose Organizational Unit
    while:
      name: ou_confirmed
      value: false
      restart: name_clash
    actions:

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

      # Check for existing users contained immediately in the OU.
      - active_directory.users.search:
          search_params:
            cn: "{{ cn }}"
          one_level: true
        load:
          search_base: organizational_unit.distinguishedName
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A user named '{{ cn }}' already exists in '{{ organizational_unit.name }}', please select again.
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: name_clash
          value: true
        when: search_result.total > 0

      # Check for existing groups contained immediately in the OU.
      - active_directory.groups.search:
          search_params:
            cn: "{{ cn }}"
          one_level: true
        load:
          search_base: organizational_unit.distinguishedName
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A group named '{{ cn }}' already exists in '{{ organizational_unit.name }}', please select again.
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: name_clash
          value: true
        when: search_result.total > 0

      - ppa.ui.output_markdown:
          doc: >
            Group **{{ cn }}** will be created in the **{{ organizational_unit.name }}** Organizational Unit.

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the Organizational Unit again.
        when: not confirm

      - set:
          name: ou_confirmed
          value: true
        when: confirm


  - name: Create Group
    actions:

      - ppa.ui.output_progress:
          text: Creating new group...
          percent: null
          element_id: creating

      - active_directory.groups.create:
          extra_params:
            displayName: "{{ group_details.display_name }}"
            description: "{{ group_details.description }}"
          distinguishedName: "CN={{ cn }},{{ organizational_unit.distinguishedName }}"
          group_type: "{{ group_details.group_type | lower }}"
        load:
          name: cn
          sAMAccountName: group_details.name
          domain_controller: domain_controller

      - active_directory.groups.by_samaccountname:
        load:
          sAMAccountName: group_details.name
          domain_controller: domain_controller
        save: new_group

      - ppa.ui.output_progress:
          text: New group created successfully
          percent: 100
          element_id: creating


  - name: Ask Set Managed By
    actions:

      - ppa.ui.input_confirm:
          text: Set a manager for the new group?
        save: set_manager


  - name: Select Manager
    when: set_manager
    while:
      name: manager_confirmed
      value: false
      restart: restart
    actions:

      - active_directory.users.get_interactive:
          title: Search for Manager
        load:
          domain_controller: domain_controller
        save: manager

      - ppa.ui.output_markdown:
          doc: >
            The manager for **{{ cn }}** will be set to **{{ manager.cn }}**.

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the manager again.
        when: not confirm

      - set:
          name: manager_confirmed
          value: true
        when: confirm


  - name: Set Manager
    when: set_manager
    actions:

      - ppa.ui.output_progress:
          text: Setting group manager...
          element_id: set_manager

      - active_directory.groups.set_attribute:
          name: managedBy
        load:
          value: manager.distinguishedName
          distinguishedName: new_group.distinguishedName
          domain_controller: domain_controller

      - ppa.ui.output_progress:
          text: Set group manager
          percent: 100
          element_id: set_manager


  - name: Ask Add To Groups
    actions:

      - ppa.ui.input_confirm:
          text: Add the new group to existing groups?
        save: add_to_groups


  - name: Audit Groups
    when: add_to_groups
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Group Search


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


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

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

      - active_directory.organizational_units.select_one:
          text: Select an Organizational Unit
        load:
          organizational_units: all_organizational_units
        save: search_scope
        when: search

      - ppa.ui.output_progress:
          text: Getting groups from Active Directory...
          percent: null
          element_id: getting_groups

      - active_directory.groups.get_all:
        load:
          search_base: search_scope.distinguishedName
          domain_controller: domain_controller
        save: groups
        when: search

      - active_directory.groups.get_all:
        load:
          domain_controller: domain_controller
        save: groups
        when: not search

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


  - name: Filter Groups (Domain Local)
    when: add_to_groups and group_details.group_type == "Domain Local"
    actions:

      - ppa.ui.output_info:
          text: As the new group type is domain local, it can only be added to other domain local groups.

      - ppa.ui.input_accept:
          text: OK

      - ppa_tools.dictionaries.filter_from_list:
          filters:
            - key: groupType
              type: not_equal
              value: Local Security Group
        load:
          dictionaries: groups
        save: groups


  - name: Select Group(s)
    when: add_to_groups
    while:
      name: groups_confirmed
      value: false
    actions:

      - active_directory.groups.select:
          text: Select Groups
          minimum: 1
        load:
          groups: groups
        save: group_selection

      - active_directory.groups.display:
          text: Selected Groups
        load:
          groups: group_selection.all

      - ppa.ui.input_confirm:
          text: Are these groups correct?
        save: groups_confirmed

      - ppa.ui.output_error:
          text: Please select the groups again.
        when: not groups_confirmed


  - name: Add To Group(s)
    when: add_to_groups
    actions:

      - ppa.ui.output_progress:
          text: Adding group to {{ group_selection.total }} groups...
          percent: null
          element_id: add_to_groups

      - active_directory.groups.add_member:
        load:
          member_distinguishedName: new_group.distinguishedName
          group_distinguishedName: group.distinguishedName
          domain_controller: domain_controller
        for_each:
          items: group_selection.all
          name: group

      - ppa.ui.output_progress:
          text: Successfully added group to {{ group_selection.total }} group(s)
          percent: 100
          element_id: add_to_groups


  - name: Ask Add Users
    actions:

      - ppa.ui.input_confirm:
          text: Add users to the new group?
        save: add_users


  - name: Audit Users
    when: add_users
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### User Search


            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_confirm:
          text: Please choose an option
          confirm: Choose Organizational Unit
          cancel: Get All Users
        save: search

      - active_directory.organizational_units.select_one:
          text: Select an Organizational Unit
        load:
          organizational_units: all_organizational_units
        save: search_scope
        when: search

      - 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_scope.distinguishedName
          domain_controller: domain_controller
        save: users
        when: search

      - active_directory.users.get_all:
        load:
          domain_controller: domain_controller
        save: users
        when: not search

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


  - name: Select Users
    when: add_users
    while:
      name: users_confirmed
      value: false
    actions:

      - active_directory.users.select:
          text: Select Users
          minimum: 1
        load:
          users: users
        save: user_selection

      - active_directory.users.display:
          text: Selected Users
        load:
          users: user_selection.all

      - ppa.ui.input_confirm:
          text: Are these users correct?
        save: users_confirmed

      - ppa.ui.output_error:
          text: Please select the users again.
        when: not users_confirmed


  - name: Add Users
    when: add_users
    actions:

      - ppa.ui.output_progress:
          text: Adding {{ user_selection.total }} users to the new group...
          percent: null
          element_id: add_users

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

      - ppa.ui.output_progress:
          text: Successfully added {{ user_selection.total }} user(s) to the new group
          percent: 100
          element_id: add_users


  - name: New Group Summary
    actions:

      - active_directory.groups.by_samaccountname:
        load:
          sAMAccountName: new_group.sAMAccountName
          domain_controller: domain_controller
        save: updated_group

      - ppa.ui.output_markdown:
          doc: >
            ## Summary


            ### New Group Details


            **Name:** {{ updated_group.sAMAccountName }}


            **Display Name:** {{ updated_group.cn }}


            **Group Type:** {{ group_details.group_type }}


            **Manager:** {{ manager.cn if set_manager else '_not supplied_' }}


            **Description:** {{ updated_group.description or '_not supplied_' }}


            **Directory Location:** {{ updated_group.distinguishedName }}


            ### Group Memberships

            {% if add_to_groups %}

            The security group was added to {{ group_selection.total }} other group(s).

            {% else %}

            The security group was not added to any other groups.

            {% endif %}

            {% if add_users %}

            {{ user_selection.total }} user(s) were added to the security group.

            {% else %}

            No users were added to the security group.

            {% endif %}


  - name: Show Group Memberships
    when: add_to_groups
    actions:

      - ppa.ui.input_confirm:
          text: Show Group Memberships?
        save: show_groups

      - active_directory.groups.display:
          text: Group Memberships
        load:
          groups: group_selection.all
        when: show_groups


  - name: Show Users In Group
    when: add_users
    actions:

      - ppa.ui.input_confirm:
          text: Show Users in Group?
        save: show_users

      - active_directory.users.display:
          text: Users in Group
        load:
          users: user_selection.all
        when: show_users
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, & Organizational Units
Required Vault Details

Active Directory
IP/DNS address of a Domain Controller
Domain FQDN
Username
Password
The Active Directory credentials need permission to create a user & add them to 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:
Provide the new group details & directory location
Add the new group to existing groups (optional)
Add users to the new group (optional)
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.