Active Directory: Containers

Summary

This module contains actions related to Active Directory Containers.

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

by_distinguishedname

Get a container by its 'distinguishedName' attribute.

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController dictionary

• distinguishedName: The container's distinguishedName

Output

A single Container.

Example

- active_directory.containers.by_distinguishedname:
    distinguishedName: CN=Engineers,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: example_container

active_directory.containers.

create

Create a new container.

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController

• name: the new container name

• distinguishedName: the new container distinguishedName

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

Output

Nothing is outputted by this action.

Example

- active_directory.containers.create:
    name: Example CN
    distinguishedName: CN=Example CN,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller

active_directory.containers.

delete

Delete a container.

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController

• distinguishedName: the distinguishedName of the container to delete

Output

Nothing is outputted by this action.

Example

- active_directory.containers.delete:
    distinguishedName: CN=Example CN,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller

active_directory.containers.

display

Display containers in a table.

The table will have the following columns:

• Name
• Distinguished Name

Minimum Plugin Version: 7.3.0

Input

• text: the title of the table

• containers: any number of Containers

Output

Nothing is outputted by this action.

Example

- active_directory.containers.get_all:
  load:
    domain_controller: domain_controller
  save: all_containers

- active_directory.containers.display:
    text: All Containers
  load:
    containers: all_containers

active_directory.containers.

display_tabbed

Display containers in a table with multiple tabs.

The table will have the following columns:

• Name
• Distinguished Name

Minimum Plugin Version: 7.3.0

Input

• text: the title of the table

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

Output

Nothing is outputted by this action.

Example

Auditing user accounts from 2 containers & presenting them in a tabbed table:

- set:
    name: tabs
    value: {}

- active_directory.containers.get_all:
  load:
    domain_controller: production_domain
  save: production_containers

- active_directory.containers.get_all:
  load:
    domain_controller: uat_domain
  save: uat_containers

- ppa_tools.dictionaries.insert:
    name: Production
  load:
    value: production_containers
    dictionary: tabs
  save: tabs

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

- active_directory.containers.display_tabbed:
    text: Containers
  load:
    tabs: tabs

active_directory.containers.

exists

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

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController dictionary

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

Output

A boolean is outputted by this action

• true if one or more containers are found

• false if no containers are found

Example

Searching using a unique attribute:

- active_directory.containers.exists:
    distinguishedName: CN=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.containers.

get_all

Get all containers.

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

• ignore_system: set to true to ignore the default System container & its contents (defaults to false)

Output

A list of Containers.

Example

- active_directory.containers.get_all:
  load:
    domain_controller: domain_controller
  save: all_containers

active_directory.containers.

move

Move a container to a different OU or CN.

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController

• distinguishedName: the distinguishedName of the container to move

• parent_distinguishedName: the distinguishedName of the new container parent

Output

Nothing is outputted by this action.

Example

- active_directory.containers.move:
    distinguishedName: CN=Example CN,DC=Example,DC=Domain
    parent_distinguishedName: OU=Staff,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller

active_directory.containers.

search

Search for containers using LDAP attributes & values.

Minimum Plugin Version: 7.3.0

Input

• domain_controller: a DomainController

• search_params: a dictionary containing Container 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 Containers found

• all: a list of Containers found

• first: the first Container found

• last: the last Container 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 containers in the Users CN whose cn starts with admin*:

- active_directory.containers.search:
    search_params:
      cn: admin*
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: containers

Tip

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

active_directory.containers.

select

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

The table will have the following columns:

• Name
• Distinguished Name

Minimum Plugin Version: 7.3.0

Input

• text: the title of the table

• containers: any number of Containers

• minimum: the minimum number of acceptable selections

• maximum: the maximum number of acceptable selections

Output

A Selection containing:

• total: the number of selected Containers

• all: a list of selected Containers

• first: the first selected Container

Example

- active_directory.containers.get_all:
  load:
    domain_controller: domain_controller
  save: containers

- active_directory.containers.select:
    text: Select Containers
  load:
    containers: containers
  save: selection

active_directory.containers.

select_one

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

The table will have the following columns:

• Name
• Distinguished Name

Minimum Plugin Version: 7.3.0

Input

• text: the title of the table

• containers: any number of Containers

• minimum: the minimum number of acceptable selections

• maximum: the maximum number of acceptable selections

Output

A single Container.

Example

- active_directory.containers.get_all:
  load:
    domain_controller: domain_controller
  save: all_containers

- active_directory.containers.select_one:
    text: Select an Organizational Unit
  load:
    containers: all_containers
  save: container