Active Directory Active Directory: Users

Summary

This module contains actions related to Active Directory Users.

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_info
      save: group
    
    - active_directory.users.search:
        sAMAccountName: example.user
      load:
        domain_controller: domain_controller_info
      save: user
    
    - active_directory.users.add_to_group:
      load:
        user_distinguishedName: user.distinguishedName
        group_distinguishedName: group.distinguishedName
        domain_controller: domain_controller_info
    

active_directory.users.

add_to_groups_interactive

Interactively add a user to one or more groups.

Minimum Plugin Version: 1.0.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A list of Group Dictionaries the user was added to.

Example

Triggering an interactive process where user Example User can be added to one or more groups.

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_info

active_directory.users.

by_distinguishedname

Get a user by its 'distinguishedName' attribute.

Minimum Plugin Version: 1.3.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: The user's distinguishedName

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

active_directory.users.

by_samaccountname

Get a user by its 'sAMAccountName' attribute.

Minimum Plugin Version: 1.3.0

Input
  • domain_controller: a DomainController dictionary

  • sAMAccountName: The user's sAMAccountName

Output

A single User Dictionary.

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

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_info

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_info

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

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

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_info

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_info

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

active_directory.users.

get_all

Get all users.

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

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

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

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

active_directory.users.

input_table

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

The table will have the following columns:

  • First Name
  • Surname
  • SAM Account Name
  • Email Address

Minimum Plugin Version: 1.0.0

Input
  • text: The title of the table

  • user_list: A list of User Dictionaries to display in the table

  • 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_info
  save: test_users

- active_directory.users.input_table:
    text: "Please Select >= 1 User(s)"
    minimum: 1
  load:
    user_list: 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: a distinguishedName to use as the root of the search (defaults to the root of the domain)

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

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_info

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

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

active_directory.users.

output_custom_table

Display a list of users 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 User Dictionaries to display in the table

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:
    user_list: test_users

active_directory.users.

output_table

Display a list of users in a table. The table will have the following columns:

The table will have the following columns:

  • Common Name
  • SAM Account Name
  • Email Address

Minimum Plugin Version: 1.0.0

Input
  • text: the title of the table

  • user_list: a list of User Dictionaries to display in the table

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

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

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_info

active_directory.users.

remove_from_groups_interactive

Interactively remove a user from one or more groups.

Minimum Plugin Version: 1.0.0

Input
  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the user

Output

A list of Group Dictionaries the user was removed from.

Example

Triggering an interactive process where user Example User can be removed from one or more groups.

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_info

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

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

active_directory.users.

Search for users using LDAP attributes & values.

Minimum Plugin Version: 2.0.0

Input
  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing user 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 User Dictionaries.

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

Tip

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

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

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

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_info
    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: 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.set_password_interactive:
    distinguishedName: "CN=John Smith,CN=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller_info

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_info