Active Directory Active Directory: Organizational Units

Summary

This module contains actions related to Active Directory Organizational Units.

Actions

active_directory.organizational_units.

by_distinguishedname

Get an organizational unit by its 'distinguishedName' attribute.

Minimum Plugin Version: 5.2.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: The organizational unit's distinguishedName

Output

A single Organizational Unit Dictionary.

Example
1
2
3
4
5
- active_directory.organizational_units.by_distinguishedname:
    distinguishedName: OU=Engineers,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller_info
  save: example_ou

active_directory.organizational_units.

create

Create a new organizational unit.

Minimum Plugin Version: 5.2.0

Input
  • domain_controller: a DomainController dictionary

  • name: the new organizational unit name

  • distinguishedName: the new organizational unit distinguishedName

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

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
- active_directory.organizational_units.create:
    name: example.ou
    distinguishedName: "OU=Example OU,CN=Users,DC=Example,DC=Domain"
    name: example.ou
  load:
    domain_controller: domain_controller_info

active_directory.organizational_units.

delete

Delete an organizational unit.

Minimum Plugin Version: 5.2.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the organizational unit to delete

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.organizational_units.delete:
    distinguishedName: "OU=Engineers,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller_info

active_directory.organizational_units.

exists

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

Minimum Plugin Version: 5.2.0

Input
Output

A boolean is outputted by this action

  • true if one or more organizational units are found

  • false if no organizational units are found

Example

Searching using a unique attribute:

1
2
3
4
5
- active_directory.organizational_units.exists:
    distinguishedName: "OU=Engineers,DC=Example,DC=Domain"
  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.organizational_units.

get_all

Get all organizational units.

This operation can be slow on large domains

Minimum Plugin Version: 5.2.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 Organizational Unit Dictionaries.

Example
1
2
3
4
- active_directory.organizational_units.get_all:
  load:
    domain_controller: domain_controller_info
  save: all_ous

active_directory.organizational_units.

input_table

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

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 5.2.0

Input
  • text: the title of the table

  • organizational_units: a single or list of Organizational Unit Dictionaries to display in the table

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A list of Organizational Unit 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 organizational units whose common names start with UAT

  • Saving the results as a new variable called uat_ous

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

  • The selection is saved as a new variable called selected_ous

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.organizational_units.search:
    name: UAT
  load:
    domain_controller: domain_controller_info
  save: uat_ous

- active_directory.organizational_units.input_table:
    text: "Please Select >= 1 Organizational Unit(s)"
    minimum: 1
  load:
    organizational_units: test_ous
  save: selected_ous

active_directory.organizational_units.

move

Move an organizational unit to a different OU or CN.

Minimum Plugin Version: 5.2.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the organizational unit to move

  • parent_distinguishedName: the distinguishedName of the new organizational unit parent

Output

Nothing is outputted by this action.

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

active_directory.organizational_units.

output_tabbed_table

Display an organizational units table with multiple tabs.

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

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 5.2.0

Input
  • text: the title of the table

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

Output

Nothing is outputted by this action.

Example

Auditing user accounts 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.organizational_units.get_all:
  load:
    domain_controller: production_domain
  save: production_ous

- active_directory.organizational_units.get_all:
  load:
    domain_controller: uat_domain
  save: uat_ous

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

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

- active_directory.organizational_units.output_tabbed_table:
    text: Active Directory Organizational Units
  load:
    tabs: tabbed_table

active_directory.organizational_units.

output_table

Display organizational units in a table.

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 5.2.0

Input
Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
7
8
9
- active_directory.organizational_units.get_all:
  load:
    domain_controller: domain_controller_info
  save: all_ous

- active_directory.organizational_units.output_table:
    text: All Organizational Units
  load:
    organizational_units: all_ous

active_directory.organizational_units.

Search for organizational units using LDAP attributes & values.

Minimum Plugin Version: 5.2.0

Input
  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing organizational unit 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 Organizational Unit Dictionaries.

Example

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

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

Tip

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