Skip to content

Active Directory Active Directory: Groups

Summary

This module contains actions related to Active Directory Groups.

Windows Server 2012

Microsoft support for Windows Server 2012 has ended.

Windows Server 2012 does not support newer & more secure TLS cipher suites required by modern versions of OpenSSL. For security reasons we will be removing support for Windows Server 2012 in a future PPA release.

To use plugin version 13 or newer with Windows Server 2012 domain controllers, you must use playbook platform alpine-3.16. This mechanism will be available for the next 6-9 months before being removed from PPA.

Actions

active_directory.groups.

add_member

Add a member to a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • group_distinguishedName: the distinguishedName of the group

  • member_distinguishedName: the distinguishedName of the new member

Output

Nothing is outputted by this action.

Example

Adding a user to a group.

  • The user & group are searched for using the sAMAccountName attribute

  • They are saved as new variables user & group

  • The required distinguishedName values are supplied using fields from the user & group variables

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- active_directory.groups.search:
    sAMAccountName: example.group
  load:
    domain_controller: domain_controller
  save: group

- active_directory.users.search:
    sAMAccountName: example.user
  load:
    domain_controller: domain_controller
  save: user

- active_directory.groups.add_member:
  load:
    group_distinguishedName: group.distinguishedName
    member_distinguishedName: member.distinguishedName
    domain_controller: domain_controller

active_directory.groups.

by_distinguishedname

Get a group by its 'distinguishedName' attribute.

Minimum Plugin Version: 1.3.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: The group's distinguishedName

Output

A single Group Dictionary.

Example
1
2
3
4
5
- active_directory.groups.by_distinguishedname:
    distinguishedName: cn=Example Group,CN=Users,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: example_group

active_directory.groups.

by_samaccountname

Get a group by its 'sAMAccountName' attribute.

Minimum Plugin Version: 1.3.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountName: The group's sAMAccountName

Output

A single Group Dictionary.

Example
1
2
3
4
5
- active_directory.groups.by_samaccountname:
    sAMAccountName: example.group
  load:
    domain_controller: domain_controller
  save: example_group

active_directory.groups.

clear_attribute

Clear a particular LDAP attribute on a group.

Works for single-valued & multi-valued string LDAP attributes.

Minimum Plugin Version: 3.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • name: the name of the LDAP attribute

Output

Nothing is outputted by this action.

Example

Searching for a group & clearing its info field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- active_directory.groups.by_samaccountname:
    sAMAccountName: Support Staff
  load:
    domain_controller: domain_controller
  save: group

- active_directory.groups.clear_attribute:
    name: info
  load:
    distinguishedName: group.distinguishedName
    domain_controller: domain_controller

active_directory.groups.

create

Create a new security group.

Minimum Plugin Version: 3.3.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountName: the new group sAMAccountName

  • name: the new group name

  • group_type: domain local, universal, or global (defaults to global)

  • distinguishedName: the new group distinguishedName

  • extra_params: a dictionary containing any extra LDAP attributes & values for the group

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.create:
    sAMAccountName: example.group
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    group_type: domain local
    name: example.group
    extra_params:
      info: An example Security Group
      cn: Example Group
  load:
    domain_controller: domain_controller

active_directory.groups.

delete

Delete a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group to delete

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.groups.delete:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.groups.

delete_attribute

Delete a certain value from a group attribute.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • name: the name of the LDAP attribute

  • value: the value to delete

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.groups.get_interactive:
    cn: Example Group
  load:
    domain_controller: domain_controller
  save: group

- active_directory.groups.delete_attribute:
    name: info
  load:
    distinguishedName: group.distinguishedName
    value: group.info
    domain_controller: domain_controller

active_directory.groups.

display

Display groups in a table.

The table will have the following columns by default:

  • Common Name
  • Description
  • Type

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.13.0

Input

  • text: the title of the table

  • groups: any number of Groups

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.search:
    cn: Operations
  load:
    domain_controller: domain_controller
  save: operations_groups

- active_directory.groups.display:
    text: Operations Groups
  load:
    groups: operations_groups

active_directory.groups.

display_tabbed

Display a groups table with multiple tabs.

This action can be used to display group lists from multiple Active Directories.

The table will have the following columns:

  • Common Name
  • Description
  • Type

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • tabs: a dictionary where each key is a tab name & each value is any number of Groups

Output

Nothing is outputted by this action.

Example

Auditing groups from 2 domains & presenting them in a tabbed table:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
- set:
    name: tabs
    value: {}

- active_directory.groups.get_all:
  load:
    domain_controller: production_domain
  save: production_groups

- active_directory.groups.get_all:
  load:
    domain_controller: uat_domain
  save: uat_groups

- ppa_tools.dictionaries.insert:
    name: Production Active Directory
  load:
    value: production_groups
    dictionary: tabs
  save: tabs

- ppa_tools.dictionaries.insert:
    name: UAT Active Directory
  load:
    value: uat_groups
    dictionary: tabs
  save: tabs

- active_directory.groups.display_tabbed:
    text: Active Directory Groups
  load:
    tabs: tabs

active_directory.groups.

exists

Search for groups using LDAP attributes & values to identify if any were found.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing group keys & values to use in the search

Output

A boolean is outputted by this action

  • true if one or more groups are found

  • false if no groups are found

Example

Searching using a unique attribute:

1
2
3
4
5
- active_directory.groups.exists:
    distinguishedName: "CN=Group Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: item_exists

Searching using a non-unique attribute:

1
2
3
4
5
- active_directory.groups.exists:
    cn: "My Group*"
  load:
    domain_controller: domain_controller
  save: item_exists

Wildcard Searching

It is possible to use * as a wildcard at the end of search values, but this can make the search slow.

active_directory.groups.

get_all

Get all groups.

This operation can be slow on large domains

Minimum Plugin Version: 6.1.0

Input

  • domain_controller: a DomainController dictionary

  • search_base: optional start point for the search (see here for more information)

  • one_level: set to true to only search one level (see here for more information)

Output

A list of Group Dictionaries.

Example
1
2
3
4
- active_directory.groups.get_all:
  load:
    domain_controller: domain_controller
  save: all_groups

active_directory.groups.

get_computers

Get computers from a group's membership list.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguished name of the group

  • nested: set to true to include nested group members in the search

Output

A list of Computers.

Warning

Getting nested group memberships can be slow.

Example

  • Getting all computers in Example Group

  • The results are saved as a new variable called computer_list

1
2
3
4
5
6
- active_directory.groups.get_computers:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: computer_list

active_directory.groups.

get_groups

Get groups from a group's membership list.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguished name of the group

  • nested: set to true to include nested group members in the search

Output

A list of Groups.

Warning

Getting nested group memberships can be slow.

Example

Getting all groups in Example Group, & saving them as a new variable called group_list. 

1
2
3
4
5
6
- active_directory.groups.get_groups:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: group_list

active_directory.groups.

get_interactive

Start an interactive search for a group using its 'Common Name'.

Minimum Plugin Version: 2.0.0

Input

  • domain_controller: a DomainController dictionary

  • title: a title displayed to the Task Operator (defaults to Get Security Group)

  • exclude: a dictionary containing LDAP attribute names & regular expressions to test their values

  • search_base: optional start point for the search (see here for more information)

Output

A single Group.

Automatic Wildcards

When using this action all provided search terms will have a wildcard appended.

Example

  • Interactively searching for a group inside the builtin Users CN

  • All groups whose cn contains admin are excluded from the results

1
2
3
4
5
6
7
- active_directory.groups.get_interactive:
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
    exclude:
      cn: .*admin.*
  load:
    domain_controller: domain_controller
  save: group

active_directory.groups.

get_members

Get the members of a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguished name of the group

  • nested: set to true to include nested group members in the search

Output

A list of Users, Groups, & Computers.

Warning

Getting nested group memberships can be slow.

Example

Getting all members of Example Group, & saving them as a new variable called group_members. 

1
2
3
4
5
6
- active_directory.groups.get_members:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: group_members

active_directory.groups.

get_users

Get users from a group's membership list.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguished name of the group

  • nested: set to true to include nested group members in the search

Output

A list of Users.

Warning

Getting nested group memberships can be slow.

Example

Getting all users in Example Group, & saving them as a new variable called user_list. 

1
2
3
4
5
6
- active_directory.groups.get_users:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: user_list

active_directory.groups.

group_memberships

Get the group memberships of a group.

Minimum Plugin Version: 8.3.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • nested: Set to true to include nested group memberships in the search

Output

A list of Groups.

Warning

Getting nested group memberships can be slow.

Example

  • Getting all group memberships for group Example Group

  • Saving the results as a new variable called group_memberships

1
2
3
4
5
6
- active_directory.groups.group_memberships:
    distinguishedName: "CN=Example Group,OU=Groups,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: group_memberships

active_directory.groups.

has_user

Determine whether the supplied user is a member of the supplied group.

This is a direct membership check only, nested memberships are not included.

Minimum Plugin Version: 7.4.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the group distinguishedName

  • user_distinguishedName: the user distinguishedName

Output

A boolean is outputted by this action

  • true if the user is in the group

  • false if the user is not in the group

Example
- active_directory.groups.has_user:
    distinguishedName: CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain,DC=Com
    user_distinguishedName: CN=Example User,CN=Users,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: user_in_group

active_directory.groups.

input_table

Display groups in a table, & allow the task operator to make a selection.

The table will have the following columns:

  • Common Name
  • Description
  • Type

Deprecation Warning

This action will soon be deprecated in favour of select.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • groups: a single or list of Group Dictionaries to display in the table

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A list of Group Dictionaries.

Tip
  • If neither a minimum or maximum is provided, the task operator will be able to submit 0 selections.
  • If minimum or maximum are provided, the operation will repeat until the task operator makes a valid number of selections.
Example

  • Getting all groups whose common names start with Test

  • Saving the results as a new variable called test_groups

  • Using this action to show the test_groups in a table, requiring the task operator selects at least 1

  • The selection is saved as a new variable called selected_groups

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.groups.search:
    cn: Test*
  load:
    domain_controller: domain_controller
  save: test_groups

- active_directory.groups.input_table:
    text: "Please Select >= 1 Group(s)"
    minimum: 1
  load:
    groups: test_groups
  save: selected_groups

active_directory.groups.

member_of

Get groups the supplied group is a direct member of.

Minimum Plugin Version: 9.4.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

Output

A list of Groups.

Example
1
2
3
4
5
- active_directory.groups.member_of:
    distinguishedName: "CN=Example Group,OU=Groups,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: member_of

active_directory.groups.

move

Move a group to a different OU or CN.

Minimum Plugin Version: 1.5.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group to move

  • parent_distinguishedName: the distinguishedName of the OU or CN to move the group to

Output

Nothing is outputted by this action.

Example

Moving a group from the 'Users' CN to the 'Staff Groups' OU:

1
2
3
4
5
- active_directory.groups.move:
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    parent_distinguishedName: "OU=Staff Groups,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.groups.

output_custom_table

Display groups in a table using custom headers & LDAP attributes.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • header: a list of column names

  • attributes: a list of LDAP attributes (one for each column name in the header)

  • groups: a single or list of Group Dictionaries to display in the table

Output

Nothing is outputted by this action.

Example

Showing cn & groupType for groups in the variable test_groups.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.output_custom_table:
    text: Custom Groups Table
    header:
      - Common Name
      - Group Type
    attributes:
      - cn
      - groupType
  load:
    groups: test_groups

active_directory.groups.

output_tabbed_table

Display a groups table with multiple tabs.

This action can be used to display group lists from multiple Active Directories.

The table will have the following columns:

  • Common Name
  • Description
  • Type

Deprecation Warning

This action will soon be deprecated in favour of display_tabbed.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • tabs: a dictionary where each key is a tab name & each value is a list of Group dictionaries

Output

Nothing is outputted by this action.

Example

Auditing groups from 2 domains & presenting them in a tabbed table:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
- set:
    name: tabbed_table
    value: {}

- active_directory.groups.get_all:
  load:
    domain_controller: production_domain
  save: production_groups

- active_directory.groups.get_all:
  load:
    domain_controller: uat_domain
  save: uat_groups

- ppa_tools.dictionaries.insert:
    name: Production Active Directory
  load:
    value: production_groups
    dictionary: tabbed_table
  save: tabbed_table

- ppa_tools.dictionaries.insert:
    name: UAT Active Directory
  load:
    value: uat_groups
    dictionary: tabbed_table
  save: tabbed_table

- active_directory.groups.output_tabbed_table:
    text: Active Directory Groups
  load:
    tabs: tabbed_table

active_directory.groups.

output_table

Display groups in a table.

The table will have the following columns:

  • Common Name
  • Description
  • Type

Deprecation Warning

This action will soon be deprecated in favour of display.

Minimum Plugin Version: 5.0.0

Input
Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.search:
    cn: Operations
  load:
    domain_controller: domain_controller
  save: operations_groups

- active_directory.groups.output_table:
    text: Operations Groups
  load:
    groups: operations_groups

active_directory.groups.

remove_member

Remove a member from a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • group_distinguishedName: the distinguishedName of the group

  • member_distinguishedName: the distinguishedName of the member to remove

Output

Nothing is outputted by this action.

Example

Removing user Example User from the group Example Group.

1
2
3
4
5
- active_directory.groups.remove_member:
    group_distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    member_distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.groups.

replace_attribute

Replace a group attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • name: the name of the LDAP attribute

  • value: the value to set

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.groups.get_interactive:
    cn: Example Group
  load:
    domain_controller: domain_controller
  save: group

- active_directory.groups.replace_attribute:
    name: info
    value: Example Info Value
  load:
    distinguishedName: group.distinguishedName
    domain_controller: domain_controller

active_directory.groups.

review_users

Review all users with a direct membership to the supplied group.

If a user should be in the group, their membership is confirmed by selecting them in the table.

If a user should not be in the group, they should be left unselected in the table.

This action can also remove unselected users from the group (see below for more).

Minimum Plugin Version: 5.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • remove: when true PPA will remove unselected users from the group (defaults to false)

Removing Unselected Users

By default PPA will not remove unselected users from the group.

This default setting can be used to collect proposed changes without actually performing them.

To remove unselected users in this action, set the remove input to true.

PPA will always ask for confirmation before any group memberships are modified.

Output

A dictionary containing the following keys & values:

  • users_to_keep: a list of users who should be in the group

  • users_to_remove: a list of users who should not be in the group

If remove is true, the users in users_to_remove will have been removed from the group.

The users in both lists will be User Dictionaries.

Example
1
2
3
4
5
6
7
8
9
- active_directory.groups.review_users:
    remove: true
  load:
    distinguishedName: group.distinguishedName
    domain_controller: domain_controller
  save: review

- ppa.ui.output_info:
    text: PPA removed {{ review.users_to_remove | length }} users from {{ group.cn }}

active_directory.groups.

Search for groups using LDAP attributes & values.

Minimum Plugin Version: 6.0.0

Input

  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing group keys & values to use in the search

  • search_base: optional start point for the search (see here for more information)

  • one_level: set to true to only search one level (see here for more information)

Output

A SearchResult containing:

  • total: the number of Groups found

  • all: a list of Groups found

  • first: the first Group found

  • last: the last Group found

Search Result Format

The search result format was updated in version 6.0.0 of this plugin.

It is not compatible with playbooks written against previous versions.

See here for more information.

Example

Searching for all groups in the Users CN whose cn starts with admin*:

1
2
3
4
5
6
7
- active_directory.groups.search:
    search_params:
      cn: admin*
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: groups

Tip

You can use * as a wildcard at the end of search values.

active_directory.groups.

select

Display groups in a table & prompt the task operator to make a selection.

The table will have the following columns by default:

  • Common Name
  • Description
  • Type

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.13.0

Input

  • text: the title of the table

  • groups: any number of Groups to display in the table

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

  • header: optional table header (see default above)

  • fields: optional list of User keys (see default above)

Output

A Selection containing:

  • total: the number of selected Groups

  • all: a list of selected Groups

  • first: the first selected Group

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.get_all:
  load:
    domain_controller: domain_controller
  save: groups

- active_directory.groups.select:
    text: Select Groups
  load:
    groups: groups
  save: selection

active_directory.groups.

select_one

Display groups in a table & prompt the task operator to select one.

The table will have the following columns:

  • Common Name
  • Description
  • Type

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.13.0

Input

  • text: the title of the table

  • groups: any number of Groups

Output

A single Group.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.groups.get_all:
  load:
    domain_controller: domain_controller
  save: groups

- active_directory.groups.select_one:
    text: Select a Group
  load:
    groups: groups
  save: group

active_directory.groups.

set_attribute

Set a group attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the group

  • name: the name of the LDAP attribute

  • value: the value to set

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.groups.get_interactive:
    cn: Example Group
  load:
    domain_controller: domain_controller
  save: group

- active_directory.groups.set_attribute:
    name: info
  load:
    distinguishedName: group.distinguishedName
    value: Example Info Value
    domain_controller: domain_controller