Active Directory 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.search:
    sAMAccountName: example.group
  load:
    domain_controller: domain_controller_info
  save: group

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

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

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_info
  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_info
  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: 1.1.0

Input
  • domain_controller: a DomainController dictionary

  • sAMAccountName: the new group sAMAccountName

  • 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
- active_directory.groups.create:
    sAMAccountName: example.group
    distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
    extra_params:
      info: An example Security Group
      cn: Example Group
  load:
    domain_controller: domain_controller_info

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_info

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_info
  save: group

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

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_info
  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_info
  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: 2.0.0

Input
  • domain_controller: a DomainController dictionary

  • search_base: a distinguishedName to use as the root of the search (defaults to the root of the domain)

Output

A list of Group Dictionaries.

Example
1
2
3
4
- active_directory.groups.get_all:
  load:
    domain_controller: domain_controller_info
  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 Computer Dictionaries.

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_info
  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 Group Dictionaries.

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_info
  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: a distinguishedName to use as the root of the search (defaults to the root of the domain)

Output

A single Group Dictionary.

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_info
  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 User, Group, & Computer dictionaries.

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_info
  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 User Dictionaries.

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_info
  save: user_list

active_directory.groups.

input_table

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

The table will have the following columns:

  • Common Name
  • Type
  • Distinguished Name

Minimum Plugin Version: 1.0.0

Input
  • text: The title of the table.

  • group_list: A 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_info
  save: test_groups

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

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_info

active_directory.groups.

output_custom_table

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

Minimum Plugin Version: 1.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)

  • user_list: a 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:
    group_list: test_groups

active_directory.groups.

output_table

Display a list of groups in a table.

The table will have the following columns:

  • Common Name
  • Group Type
  • Distinguished Name

Minimum Plugin Version: 1.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_info
  save: operations_groups

- active_directory.groups.output_table:
    text: Operations Groups
  load:
    group_list: 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_info

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_info
  save: group

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

active_directory.groups.

Search for groups using LDAP attributes & values.

Minimum Plugin Version: 2.0.0

Input
  • domain_controller: a DomainController dictionary

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

  • search_base: a distinguishedName to use as the root of the search (defaults to the root of the domain)

Output

A list of Group Dictionaries.

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_info
  save: groups

Tip

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

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_info
  save: group

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