Active Directory: Groups
Summary
This module contains actions related to Active Directory Groups.
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.
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_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.
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.
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
, orglobal
(defaults toglobal
) -
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.
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_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.
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.
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 |
|
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 |
|
Searching using a non-unique attribute:
1 2 3 4 5 |
|
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_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_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_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_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
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_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.
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.
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.
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.
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.
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_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 |
|
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
-
text: the title of the table
-
groups: a single or list of Group Dictionaries
Output
Nothing is outputted by this action.
Example
1 2 3 4 5 6 7 8 9 10 |
|
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.
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.
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 tofalse
)
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.
search
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:
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 |
|
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
Output
A Selection containing:
Example
1 2 3 4 5 6 7 8 9 10 |
|
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.
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 |
|