Skip to content

Active Directory Active Directory: Organizational Units

Summary

This module contains actions related to Active Directory Organizational Units.

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.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.

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

active_directory.organizational_units.

create

Create a new organizational unit.

Minimum Plugin Version: 5.2.0

Input

  • domain_controller: a DomainController

  • 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
- active_directory.organizational_units.create:
    name: example.ou
    distinguishedName: "OU=Example OU,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.organizational_units.

delete

Delete an organizational unit.

Minimum Plugin Version: 5.2.0

Input

  • domain_controller: a DomainController

  • 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

active_directory.organizational_units.

display

Display organizational units in a table.

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 6.0.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
  save: all_ous

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

active_directory.organizational_units.

display_tabbed

Display organizational units in a table with multiple tabs.

The table will have the following columns:

  • Name
  • Distinguished Name

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 Organizational Units

Output

Nothing is outputted by this action.

Example

Auditing user accounts from 2 OUs & 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.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
  load:
    value: production_ous
    dictionary: tabs
  save: tabs

- ppa_tools.dictionaries.insert:
    name: UAT
  load:
    value: uat_ous
    dictionary: tabs
  save: tabs

- active_directory.organizational_units.display_tabbed:
    text: Organizational Units
  load:
    tabs: tabs

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
  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: 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 Organizational Units.

Example
1
2
3
4
- active_directory.organizational_units.get_all:
  load:
    domain_controller: domain_controller
  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

Deprecation Warning

This action will soon be deprecated in favour of select.

Minimum Plugin Version: 5.2.0

Input

  • text: the title of the table

  • organizational_units: any number of Organizational Units

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A list of Organizational Units.

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
  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

  • 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

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

Deprecation Warning

This action will soon be deprecated in favour of display_tabbed.

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

Deprecation Warning

This action will soon be deprecated in favour of display.

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
  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: 6.1.0

Input

  • domain_controller: a DomainController

  • search_params: a dictionary containing Organizational Unit 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 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
  save: organizational_units

Tip

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

active_directory.organizational_units.

select

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

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • organizational_units: any number of Organizational Units

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A Selection containing:

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

- active_directory.organizational_units.select:
    text: Select Organizational Units
  load:
    organizational_units: ous
  save: selection

active_directory.organizational_units.

select_one

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

The table will have the following columns:

  • Name
  • Distinguished Name

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • organizational_units: any number of Organizational Units

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A single Organizational Unit.

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

- active_directory.organizational_units.select_one:
    text: Select an Organizational Unit
  load:
    organizational_units: ous
  save: ou