Skip to content

Active Directory Active Directory: Users

Summary

This module contains actions related to Active Directory Users.

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

add_to_group

Add a user to a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • user_distinguishedName: the distinguishedName of the user

  • group_distinguishedName: the distinguishedName of the group

Output

Nothing is outputted by this action.

Example

Adding a user to a group.

  • The user & group are searched for using the sAMAccountName attribute, & saved as new variables user & group.

  • This action is then supplied the required distinguishedName 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
  save: group

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

- active_directory.users.add_to_group:
  load:
    user_distinguishedName: user.distinguishedName
    group_distinguishedName: group.distinguishedName
    domain_controller: domain_controller

active_directory.users.

add_to_groups_interactive

Interactively add a user to one or more groups.

Minimum Plugin Version: 11.2.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • exclude: a dictionary of Group keys & regular expression values (see below for more information)

Excluding Groups

The exclude input can be used to filter out groups from search results.

Supplying the following will filter out any group whose sAMAccountName contains admins.

    exclude:
      sAMAccountName: .*admins.*
Output

A list of Group Dictionaries the user was added to.

Example
1
2
3
4
- active_directory.users.add_to_groups_interactive:
    distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

by_distinguishedname

Get a user by its 'distinguishedName' attribute.

Minimum Plugin Version: 7.10.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: The user's distinguishedName

  • search_base: optional start point for the search (see here for more information)

Output

A single User Dictionary.

Example
1
2
3
4
5
- active_directory.users.by_distinguishedname:
    distinguishedName: cn=Example User,CN=Users,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: example_user

active_directory.users.

by_samaccountname

Get a user by its 'sAMAccountName' attribute.

Minimum Plugin Version: 7.10.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountName: The user's sAMAccountName

  • search_base: optional start point for the search (see here for more information)

Output

A single User Dictionary.

Example
1
2
3
4
5
- active_directory.users.by_samaccountname:
    sAMAccountName: example.user
  load:
    domain_controller: domain_controller
  save: example_user

active_directory.users.

can_be_delegated

Determine if the supplied user account has not been flagged as 'sensitive and not for delegation'.

Minimum Plugin Version: 4.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A boolean is outputted by this action

  • true if the user can be delegated

  • false if the user cannot be delegated

Example
1
2
3
4
5
- active_directory.users.can_be_delegated:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: can_be_delegated

active_directory.users.

clear_attribute

Clear a particular LDAP attribute on a user.

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 user

  • name: the name of the LDAP attribute

Output

Nothing is outputted by this action.

Example

Searching for a user & clearing their carLicense field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- active_directory.users.by_samaccountname:
    sAMAccountName: john.smith
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.clear_attribute:
    name: carLicense
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

create

Create a new user.

Minimum Plugin Version: 1.1.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountName: the new user sAMAccountName

  • distinguishedName: the new user distinguishedName

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

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
7
8
- active_directory.users.create:
    sAMAccountName: example.user
    distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
    extra_params:
      info: An example user
      cn: Example User
  load:
    domain_controller: domain_controller

active_directory.users.

delete

Delete a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user to delete

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.delete:
    distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

delete_attribute

Delete a certain value from a user attribute.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • name: the name of the LDAP attribute

  • value: the value to delete

Output

Nothing is outputted by this action.

Example

Clearing the existing info value of a user.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- active_directory.users.get_interactive:
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.delete_attribute:
    name: info
  load:
    distinguishedName: user.distinguishedName
    value: user.info
    domain_controller: domain_controller

active_directory.users.

disable

Disable a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.disable:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

display

Display users in a table.

The table will have the following columns by default:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.12.0

Input

  • text: the title of the table

  • users: any number of Users

  • header: optional table header (see default above)

  • fields: optional list of User keys (see default above)

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.search:
    cn: Test*
  load:
    domain_controller: domain_controller
  save: test_users

- active_directory.users.display:
    text: Test User Accounts
  load:
    users: test_users

active_directory.users.

display_tabbed

Display users in a table with multiple tabs.

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

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

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 Users

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: tabs
    value: {}

- active_directory.users.get_all:
  load:
    domain_controller: production_domain
  save: production_users

- active_directory.users.get_all:
  load:
    domain_controller: uat_domain
  save: uat_users

- ppa_tools.dictionaries.insert:
    name: Production Active Directory
  load:
    value: production_users
    dictionary: tabs
  save: tabs

- ppa_tools.dictionaries.insert:
    name: UAT Active Directory
  load:
    value: uat_users
    dictionary: tabs
  save: tabs

- active_directory.users.display_tabbed:
    text: Active Directory Users
  load:
    tabs: tabs

active_directory.users.

enable

Enable a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.enable:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

exists

Search for users 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 user keys & values to use in the search

Output

A boolean is outputted by this action

  • true if one or more users are found

  • false if no users are found

Example

Searching using a unique attribute:

1
2
3
4
5
- active_directory.users.exists:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: item_exists

Searching using a non-unique attribute: 

1
2
3
4
5
- active_directory.users.exists:
    cn: "Maddison*"
  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.users.

force_password_change

Set the 'force password change at next logon' flag against a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.force_password_change:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

get_all

Get all users.

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

Example
1
2
3
4
- active_directory.users.get_all:
  load:
    domain_controller: domain_controller
  save: all_users

active_directory.users.

get_disabled

Get disabled users.

This operation can be slow on large domains

Minimum Plugin Version: 7.12.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 disabled Users.

Example
1
2
3
4
- active_directory.users.get_disabled:
  load:
    domain_controller: domain_controller
  save: disabled_users

active_directory.users.

get_enabled

Get enabled users.

This operation can be slow on large domains

Minimum Plugin Version: 7.12.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 enabled Users.

Example
1
2
3
4
- active_directory.users.get_enabled:
  load:
    domain_controller: domain_controller
  save: enabled_users

active_directory.users.

get_free_samaccountname

Takes a list of sAMAccountNames & finds the first that is currently available.

This can use useful in new joiner tasks when multiple naming formats are acceptable.

Minimum Plugin Version: 7.9.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountNames: a list of sAMAccountNames to check

Output

Either the first available sAMAccountName or null if they are all in use.

Example
1
2
3
4
5
6
7
8
- active_directory.users.get_free_samaccountname:
    sAMAccountNames:
      - example.user
      - e.user
      - exampleuser
  load:
    domain_controller: domain_controller
  save: available_name

active_directory.users.

get_free_uid_numbers

Get uidNumbers in a supplied range that are not assigned to any users.

Minimum Plugin Version: 4.2.0

Input

  • domain_controller: a DomainController dictionary

  • start: the start of the range

  • end: the end of the range

  • quantity: the number of free uidNumbers you require

  • block_size: how many numbers to query at once (defaults to 5)

Search Performance

This action queries the domain controller for each block of numbers in the supplied range.

If this action performs slowly, use a higher block_size to reduce the number of queries.

The action stops as soon as the supplied quantity is met, so use the lowest acceptable quantity for best results.

Output

A list of numbers in the supplied range that are not used as any user's uidNumber.

Example

Getting 100 unused uidNumbers between 20,000 & 30,000:

1
2
3
4
5
6
7
- active_directory.users.get_free_uid_numbers:
    start: 20000
    end: 30000
    quantity: 100
  load:
    domain_controller: domain_controller
  save: free_uid_numbers

active_directory.users.

get_free_userprincipalname

Takes a list of userPrincipalNames & finds the first that is currently available.

This can use useful in new joiner tasks when multiple naming formats are acceptable.

Minimum Plugin Version: 7.9.0

Input

  • domain_controller: a DomainController dictionary

  • userPrincipalNames: a list of userPrincipalNames to check

Output

Either the first available userPrincipalName or null if they are all in use.

Example
1
2
3
4
5
6
7
8
- active_directory.users.get_free_userprincipalname:
    userPrincipalNames:
      - example.user@example.domain
      - e.user@example.domain
      - exampleuser@example.domain
  load:
    domain_controller: domain_controller
  save: available_name

active_directory.users.

get_interactive

Start an interactive search for a user.

Minimum Plugin Version: 2.0.0

Input

  • domain_controller: a DomainController dictionary

  • title: a title displayed to the Task Operator (defaults to Get User Account)

  • search_attribute: an attribute from the following list:

    • sAMAccountName (default value)
    • cn
    • mail

  • exclude: a dictionary of User keys & regular expression values (see below for more information)

  • search_base: optional start point for the search (see here for more information)

Excluding Users

The exclude input can be used to filter out users from search results.

Supplying the following will filter out any user whose sAMAccountName contains admin.

    exclude:
      sAMAccountName: .*admin.*
Output

A single User Dictionary.

Automatic Wildcards

When using this action all provided search terms will have a wildcard appended.

Example

  • Interactively searching for a user inside the builtin Users CN

  • All users whose sAMAccountName contains admin are excluded from the results

1
2
3
4
5
6
7
- active_directory.users.get_interactive:
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
    exclude:
      sAMAccountName: .*admin.*
  load:
    domain_controller: domain_controller
  save: user

active_directory.users.

get_password_expiry

Find out when a user's password will expire.

Minimum Plugin Version: 7.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • maximum_password_age: optional maximum password age outputted by this action

Running Against Multiple Users

If the maximum_password_age input is not supplied, the action will get it from the domain.

If your task runs this action on many users, we recommended supplying this input.

While this has only a small impact on performance, it will result in far fewer connections to Active Directory.

Output

A single PasswordExpiry or null if any of the following are true:

  • The domain has no maximum password age

  • The user does not have a password set

  • The user's password is set to never expire

Example 1 - Getting Single Expiry
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- active_directory.users.get_password_expiry:
    distinguishedName: CN=Full Name,OU=Example,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: expiry

- ppa.ui.output_markdown:
    doc: >
      The user's password will expire on {{ expiry.timestamp }}.

      Time remaining:

      **Days:** {{ expiry.days }}

      **Hours:** {{ expiry.hours }}

      **Minutes:** {{ expiry.minutes }}
Example 2 - Getting Multiple Expiries

  • Getting the maximum password age separately & supplying it to this action

  • Running the action against a sequence of users

  • Supplying the maximum password age to the action means it is only fetched once

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.domain.get_maximum_password_age:
  load:
    domain_controller: domain_controller
  save: maximum_password_age

- active_directory.users.get_password_expiry:
  load:
    distinguishedName: loop.action.item.value.distinguishedName
    maximum_password_age: maximum_password_age
    domain_controller: domain_controller
  sequence: users
  save: user_password_expiries

active_directory.users.

get_uac_properties

Get a list of the supplied user's UAC properties.

Minimum Plugin Version: 7.5.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A list containing one or more of the following UAC properties assigned to the user.

See more about UAC property flags here.

  • SCRIPT

  • ACCOUNTDISABLE

  • HOMEDIR_REQUIRED

  • LOCKOUT

  • PASSWD_NOTREQD

  • PASSWD_CANT_CHANGE

  • ENCRYPTED_TEXT_PWD_ALLOWED

  • TEMP_DUPLICATE_ACCOUNT

  • NORMAL_ACCOUNT

  • INTERDOMAIN_TRUST_ACCOUNT

  • WORKSTATION_TRUST_ACCOUNT

  • SERVER_TRUST_ACCOUNT

  • DONT_EXPIRE_PASSWORD

  • MNS_LOGON_ACCOUNT

  • SMARTCARD_REQUIRED

  • TRUSTED_FOR_DELEGATION

  • NOT_DELEGATED

  • USE_DES_KEY_ONLY

  • DONT_REQ_PREAUTH

  • PASSWORD_EXPIRED

  • TRUSTED_TO_AUTH_FOR_DELEGATION

  • PARTIAL_SECRETS_ACCOUNT

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
- active_directory.users.get_uac_properties:
    distinguishedName: "CN=Example User,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: uac_properties

- ppa.ui.output_markdown:
    doc: >
      ### UAC Properties

      **User:** Example User

      **Flags:**

      {% for property in uac_properties %}

      - {{ property }}

      {% endfor %}

active_directory.users.

group_memberships

Get the group memberships of a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • nested: Set to true to include nested group memberships in the search

Output

A list of group dictionaries.

Warning

Getting nested group memberships can be slow.

Example

  • Getting all group memberships for user Example User

  • Saving the results as a new variable called group_memberships

1
2
3
4
5
6
- active_directory.users.group_memberships:
    distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
    nested: true
  load:
    domain_controller: domain_controller
  save: group_memberships

active_directory.users.

has_reversible_password

Determine if the supplied user's password is stored using reversible encryption.

Minimum Plugin Version: 4.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A boolean is outputted by this action

  • true if the password is stored using reversible encryption

  • false if the password is not stored using reversible encryption

Example
1
2
3
4
5
- active_directory.users.has_reversible_password:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: reversible

active_directory.users.

input_table

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

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

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

  • users: a single or list of User Dictionaries

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A list of User 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 users whose common names start with Test

  • Saving the results as a new variable called test_users

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

  • The selection is saved as a new variable called selected_users

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.users.search:
    cn: Test*
  load:
    domain_controller: domain_controller
  save: test_users

- active_directory.users.input_table:
    text: "Please Select >= 1 User(s)"
    minimum: 1
  load:
    users: test_users
  save: selected_users

active_directory.users.

members_of

Find users who are members of any of the supplied groups.

Minimum Plugin Version: 3.0.0

Input

  • domain_controller: a DomainController dictionary

  • group_distinguishedNames: a list of group distinguishedNames

  • search_base: optional start point for the search (see here for more information)

Output

A list of User Dictionaries.

Search Speed

This operation can be slow on a large domain, especially if multiple groups are supplied.

Consider targeting the search using search_base where possible.

Single Group

Finding users in the Remote Desktop Users group:

1
2
3
4
5
6
- active_directory.users.members_of:
    group_distinguishedNames:
      - CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: users
Targeted Search & Multiple Groups

Finding all users who are:

  • In the default Users CN

  • In either the Account Operators or Remote Desktop Users groups

1
2
3
4
5
6
7
8
- active_directory.users.members_of:
    group_distinguishedNames:
      - CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain,DC=Com
      - CN=Account Operators,CN=Users,DC=Example,DC=Domain,DC=Com
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: users

active_directory.users.

membership_report

Displays a report on the user's direct & indirect group memberships.

Along with statistics on direct/indirect group memberships, a table will be shown with:

  • Each of the supplied user's direct group memberships
  • The number of memberships inherited from each direct membership
  • The maximum nesting depth for each direct membership

The task operator will have the option of viewing a more detailed table containing:

  • Each of the supplied user's direct group memberships
  • Every membership inherited from each direct membership
  • The nesting depth of each inherited membership

Minimum Plugin Version: 9.5.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • max_depth: the maximum number of membership layers to audit (defaults to 10)

Setting max_depth to a higher number can make this action slow.

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.membership_report:
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

move

Move a user to a different OU or CN.

Minimum Plugin Version: 1.5.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user to move

  • parent_distinguishedName: the distinguishedName of the OU or CN to move the user to

Output

Nothing is outputted by this action.

Example

Moving a user from the 'Users' CN to the 'Staff' OU:

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

active_directory.users.

not_members_of

Find users who are not members of any of the supplied groups.

Minimum Plugin Version: 3.0.0

Input

  • domain_controller: a DomainController dictionary

  • group_distinguishedNames: a list of group distinguishedNames

  • search_base: optional start point for the search (see here for more information)

Output

A list of User Dictionaries.

Search Speed

This operation can be slow on a large domain, especially if multiple groups are supplied.

Consider targeting the search using search_base where possible.

Single Group

Finding all users not in the Remote Desktop Users group:

1
2
3
4
5
6
- active_directory.users.not_members_of:
    group_distinguishedNames:
      - CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: users
Targeted Search & Multiple Groups

Finding all users who are:

  • In the default Users CN

  • Not in either the Account Operators or Remote Desktop Users groups

1
2
3
4
5
6
7
8
- active_directory.users.not_members_of:
    group_distinguishedNames:
      - CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain,DC=Com
      - CN=Account Operators,CN=Users,DC=Example,DC=Domain,DC=Com
    search_base: CN=Users,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: users

active_directory.users.

output_custom_table

Display users 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)

  • users: any number of Users

Output

Nothing is outputted by this action.

Example

Showing mail, distinguishedName, & userAccountControl for users in the variable test_users.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.users.output_custom_table:
    text: Custom Users Table
    header:
      - Email Address
      - Distinguished Name
      - User Account Control
    attributes:
      - mail
      - distinguishedName
      - userAccountControl
  load:
    users: test_users

active_directory.users.

output_tabbed_table

Display users in a table with multiple tabs.

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

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

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 Users

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.users.get_all:
  load:
    domain_controller: production_domain
  save: production_users

- active_directory.users.get_all:
  load:
    domain_controller: uat_domain
  save: uat_users

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

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

- active_directory.users.output_tabbed_table:
    text: Active Directory Users
  load:
    tabs: tabbed_table

active_directory.users.

output_table

Display users in a table.

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

Deprecation Warning

This action will soon be deprecated in favour of display.

Minimum Plugin Version: 5.0.0

Input
Output

Nothing is outputted by this action.

Example

  • Getting all users whose common names start with Test

  • Saving the results as a new variable called test_users

  • Using this action to show the test_users in a table

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.search:
    cn: Test*
  load:
    domain_controller: domain_controller
  save: test_users

- active_directory.users.output_table:
    text: Test User Accounts
  load:
    users: test_users

active_directory.users.

password_has_expired

Determine if the supplied user account's password has expired.

Minimum Plugin Version: 7.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • maximum_password_age: optional maximum password age outputted by this action

Running Against Multiple Users

If the maximum_password_age input is not supplied, the action will get it from the domain.

If your task runs this action on many users, we recommended supplying this input.

While this has only a small impact on performance, it will result in far fewer connections to Active Directory.

Output

A boolean is outputted by this action

  • true if the user's password has expired

  • false if the user's password has not expired

Example
1
2
3
4
5
- active_directory.users.password_has_expired:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: password_expired

active_directory.users.

password_not_required

Determine if the supplied user account can have a blank password.

Minimum Plugin Version: 4.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A boolean is outputted by this action

  • true if the user's password can be blank

  • false if the user's password cannot be blank

Example
1
2
3
4
5
- active_directory.users.password_not_required:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: password_not_required

active_directory.users.

password_will_expire

Determine if the supplied user account's password has an expiry.

Minimum Plugin Version: 4.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A boolean is outputted by this action

  • true if the user's password will expire

  • false if the user's password will not expire

Example
1
2
3
4
5
- active_directory.users.password_will_expire:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: password_will_expire

active_directory.users.

remove_from_group

Remove a user from a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • user_distinguishedName: the distinguishedName of the user

  • group_distinguishedName: The distinguishedName of the group

Output

Nothing is outputted by this action.

Example

Removing user Example User from the group Example Group. 

1
2
3
4
5
- active_directory.user.remove_from_group:
    user_distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
    group_distinguishedName: "CN=Example Group,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

remove_from_groups_interactive

Interactively remove a user from one or more groups.

Minimum Plugin Version: 11.2.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • exclude: a dictionary of Group keys & regular expression values (see below for more information)

Excluding Groups

The exclude input can be used to filter out groups from search results.

Supplying the following will filter out any group whose sAMAccountName contains admins.

    exclude:
      sAMAccountName: .*admins.*
Output

A list of Group Dictionaries the user was removed from.

Example
1
2
3
4
- active_directory.users.remove_from_groups_interactive:
    distinguishedName: "CN=Example User,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

replace_attribute

Replace a user attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • 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
- active_directory.users.get_interactive:
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.replace_attribute:
    name: info
    value: Example Info Value
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

Search for users using LDAP attributes & values.

Minimum Plugin Version: 6.1.0

Input

  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing user 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 search one level (see here for more information)

Output

A SearchResult containing:

  • total: the number of Users found

  • all: a list of Users found

  • first: the first User found

  • last: the last User 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.

Search Speed

This operation can be slow on a large domain.

Consider targeting the search using search_base where possible.

Example

Searching for all users in the Users CN whose sAMAccountName starts with admin:

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

Tip

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

active_directory.users.

select

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

The table will have the following columns by default:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.12.0

Input

  • text: the title of the table

  • users: any number of Users

  • minimum: the minimum number of selections

  • maximum: the maximum number of selections

  • header: optional table header (see default above)

  • fields: optional list of User keys (see default above)

Output

A Selection containing:

  • total: the number of selected Users

  • all: a list of selected Users

  • first: the first selected User

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

- active_directory.users.select:
    text: Select Users
  load:
    users: users
  save: selection

active_directory.users.

select_one

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

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address
  • Enabled
  • Locked

These can be customised by supplying the header & fields inputs.

Minimum Plugin Version: 7.12.0

Input

  • text: the title of the table

  • users: any number of Users

  • header: optional table header (see default above)

  • fields: optional list of User keys (see default above)

Output

A single User.

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

- active_directory.users.select_one:
    text: Select a User
  load:
    users: users
  save: user

active_directory.users.

set_attribute

Set a user attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • 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
- active_directory.users.get_interactive:
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.set_attribute:
    name: info
    value: Example Info Value
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

set_attributes

Set multiple user attribute values.

This action clears & then sets each supplied attribute.

Multi-value string attributes are not supported by this action.

Minimum Plugin Version: 7.11.0

Input
Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- active_directory.users.get_interactive:
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.set_attributes:
    attributes:
      - name: info
        value: Example Info Value
      - name: description
        value: Example description
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

set_manager

Set a user's manager.

Minimum Plugin Version: 9.4.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • manager_distinguishedName: the distinguishedName of the manager

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
- active_directory.users.by_samaccountname:
    sAMAccountName: user
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.by_samaccountname:
    sAMAccountName: manager
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.set_manager:
  load:
    distinguishedName: user.distinguishedName
    manager_distinguishedName: manager.distinguishedName
    domain_controller: domain_controller

active_directory.users.

set_password

Set a user's password.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

  • password: the new password

Output

Nothing is outputted by this action.

Example

  • Setting the password for user John Smith in the root Users CN

  • The PPA UI input_password action is used to get & save the new password

1
2
3
4
5
6
7
8
9
- ppa.ui.input_password:
    text: New Password
  save: new_password

- active_directory.users.set_password:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
    password: new_password

active_directory.users.

set_password_interactive

Interactively set a user's password. This operation:

  • Asks the task operator to supply & confirm a new password.
  • Attempts to set the password for the user.
  • If the password is refused by Active Directory the operation will be repeated repeated.

Minimum Plugin Version: 5.6.0

Input
  • domain_controller: a DomainController dictionary
  • distinguishedName: the distinguishedName of the user
Output

The password that was successfully set for the user.

Example
1
2
3
4
- active_directory.users.set_password_interactive:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.users.

set_password_never_expires

Set a user account to have a never-expiring password.

Minimum Plugin Version: 9.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.by_samaccountname:
    sAMAccountName: example.user
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.set_password_never_expires:
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

set_password_will_expire

Set a user account to have an expiring password.

Minimum Plugin Version: 9.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.by_samaccountname:
    sAMAccountName: example.user
  load:
    domain_controller: domain_controller
  save: user

- active_directory.users.set_password_will_expire:
  load:
    distinguishedName: user.distinguishedName
    domain_controller: domain_controller

active_directory.users.

smart_card_required

Determine if the supplied user account requires a smart card for interactive login.

Minimum Plugin Version: 4.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A boolean is outputted by this action

  • true if a smart card is required

  • false if a smart card is not required

Example
1
2
3
4
5
- active_directory.users.smart_card_required:
    distinguishedName: "CN=Full Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: card_required

active_directory.users.

test_credentials

Test a user's credentials. Often used after resetting a password.

Takes the same inputs a DomainController dictionary contains, but each input is supplied separately.

Minimum Plugin Version: 1.0.0

Input

  • address: the Domain Controller IP or DNS address

  • domain: the FQDN of the Active Directory domain

  • username: username for authentication

  • password: password for authentication

Output

Nothing is outputted by this action.

Example

Testing a new password for user John Smith.

  • The new_password variable was set in an earlier step (not shown)

  • Note the domain_controller dictionary is used to supply the address, port, & domain keys

1
2
3
4
5
6
7
- active_directory.users.test_credentials:
    username: john.smith
  load:
    address: domain_controller.address
    port: domain_controller.port
    domain: domain_controller.domain
    password: new_password

active_directory.users.

unlock

Unlock a user.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

Nothing is outputted by this action.

Example
1
2
3
4
- active_directory.users.unlock:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller