Create User

This is an interactive task for adding a new user to Active Directory.
Playbook Files

This playbook was built for PPA version 3.3
# The task was built to work with these plugin versions.
plugins:
  ppa: ^11.4
  ppa_tools: ^11.0
  hashicorp_vault: ^8.0
  active_directory: ^13.0


steps:

  - name: Greeting
    actions:

      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.active_directory.full }}


            ### Active Directory - New User


            Use this task to create a new Active Directory user.


            You will need to:


            - Provide user information


            - Choose where to create them in Active Directory


            - Set the user's manager (optional)


            - Select groups to add them to (optional)

      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: active_directory
          reason: Getting Active Directory details
          keys:
            - name: address
            - name: domain
            - name: username
            - name: password
              sensitive: true
          create_missing: true
        save: domain_controller


  - name: Get User Details
    while:
      name: user_confirmed
      value: false
      restart: user_exists
    actions:

      - ppa.ui.input_form:
          text: New User Details
          fields:
            - text:
                name: first_name
                title: First Name
                required: true
            - text:
                name: last_name
                title: Last Name
                required: true
            - text:
                name: sAMAccountName
                title: Logon Name
                required: true
            - email:
                name: email_address
                title: Email Address
                required: false
            - text:
                name: description
                title: Description
                required: false
            - choice:
                name: password_will_expire
                title: Password Will Expire
                default: Yes
                options:
                  - Yes
                  - No
          element_id: user_details
        save: user_details

      - active_directory.users.search:
          search_params:
            sAMAccountName: "{{ user_details.sAMAccountName }}"
        load:
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A user with logon name '{{ user_details.sAMAccountName }}' already exists, please use a different one.
          element_id: "{{ user_details.sAMAccountName }}_exists"
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: user_exists
          value: true
        when: search_result.total > 0

      - set:
          value: "{{ user_details.first_name | title }} {{ user_details.last_name | title }}"
          name: cn

      - ppa.ui.output_markdown:
          doc: >
            ### New User Details


            **First Name:** {{ user_details.first_name | title }}


            **Last Name:** {{ user_details.last_name | title }}


            **Logon Name:** {{ user_details.sAMAccountName }}


            **Email Address:** {{ user_details.email_address or '_not supplied_' }}


            **Description:** {{ user_details.description or '_not supplied_' }}


            **Password Will Expire:** {{ user_details.password_will_expire }}

      - ppa.ui.input_confirm:
          text: Are these details correct?
          confirm: Yes
          cancel: No
        save: user_confirmed

      - ppa.ui.output_error:
          text: Please supply the information again.
        when: not user_confirmed


  - name: Organizational Unit Intro
    actions:

      - ppa.ui.output_progress:
          text: Getting all Organizational Units...
          element_id: getting_ous

      - active_directory.organizational_units.get_all:
        load:
          domain_controller: domain_controller
        save: all_organizational_units

      - ppa.ui.output_progress:
          text: Got all Organizational Units
          percent: 100
          element_id: getting_ous

      - ppa.ui.output_markdown:
          doc: >
            ### User Location


            You now need to choose where to create the user in Active Directory.


            Click OK & select an Organizational Unit from the table.

      - ppa.ui.input_accept:
          text: OK


  - name: Choose Organizational Unit
    while:
      name: ou_confirmed
      value: false
      restart: name_clash
    actions:

      - active_directory.organizational_units.select_one:
          text: Select an Organizational Unit
        load:
          organizational_units: all_organizational_units
        save: organizational_unit

      # Check for existing users contained immediately in the OU.
      - active_directory.users.search:
          search_params:
            cn: "{{ cn }}"
          one_level: true
        load:
          search_base: organizational_unit.distinguishedName
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A user named '{{ cn }}' already exists in '{{ organizational_unit.name }}', please select again.
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: name_clash
          value: true
        when: search_result.total > 0

      # Check for existing groups contained immediately in the OU.
      - active_directory.groups.search:
          search_params:
            cn: "{{ cn }}"
          one_level: true
        load:
          search_base: organizational_unit.distinguishedName
          domain_controller: domain_controller
        save: search_result

      - ppa.ui.output_error:
          text: A group named '{{ cn }}' already exists in '{{ organizational_unit.name }}', please select again.
        when: search_result.total > 0

      - ppa.ui.input_accept:
          text: OK
        when: search_result.total > 0

      - set:
          name: name_clash
          value: true
        when: search_result.total > 0

      - ppa.ui.output_markdown:
          doc: >
            User **{{ cn }}** will be created in the **{{ organizational_unit.name }}** Organizational Unit.

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the Organizational Unit again.
        when: not confirm
      
      - set:
          name: ou_confirmed
          value: true
        when: confirm


  - name: Create User
    actions:

      - ppa.ui.output_progress:
          text: Creating new user...
          percent: null
          element_id: creating

      - ppa_tools.text.to_bool:
        load:
          text: user_details.password_will_expire
        save: password_will_expire

      - active_directory.users.create:
          distinguishedName: "CN={{ cn }},{{ organizational_unit.distinguishedName }}"
          extra_params:
            givenName: "{{ user_details.first_name | title }}"
            sn: "{{ user_details.last_name | title }}"
            mail: "{{ user_details.email_address }}"
            displayName: "{{ cn }}"
            cn: "{{ cn }}"
            description: "{{ user_details.description }}"
            userPrincipalName: "{{ user_details.sAMAccountName }}@{{ domain_controller.domain }}"
        load:
          sAMAccountName: user_details.sAMAccountName
          domain_controller: domain_controller

      - active_directory.users.by_samaccountname:
        load:
          sAMAccountName: user_details.sAMAccountName
          domain_controller: domain_controller
        save: new_user

      - ppa.ui.output_progress:
          text: New user created successfully
          percent: 100
          element_id: creating


  - name: Set Password & Enable
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### New User Password


            The new user has been created successfully.


            Please supply a password to set for the user.


            The user will be enabled once the password has been set.

            {% if password_will_expire %}
              
              __Note:__ The user's password will need to changed on first logon.
            
            {% else %}
              
              __Note:__ The user's password **will not** need to be changed on first logon as they have a non-expiring password._

            {% endif %}

      - active_directory.users.set_password_interactive:
        load:
          distinguishedName: new_user.distinguishedName
          domain_controller: domain_controller
        save: new_password

      - ppa.ui.output_progress:
          text: Forcing password change on next logon...
          element_id: force_change_enable
        when: password_will_expire

      - active_directory.users.force_password_change:
        load:
          distinguishedName: new_user.distinguishedName
          domain_controller: domain_controller
        when: password_will_expire

      - ppa.ui.output_progress:
          text: Enabling user...
          element_id: force_change_enable

      - active_directory.users.enable:
        load:
          distinguishedName: new_user.distinguishedName
          domain_controller: domain_controller

      - ppa.ui.output_progress:
          text: Enabled user & forced password change at next logon
          percent: 100
          element_id: force_change_enable
        when: password_will_expire

      - ppa.ui.output_progress:
          text: Enabled user
          percent: 100
          element_id: force_change_enable
        when: not password_will_expire

      - ppa.ui.output_progress:
          text: Setting password to never expire...
          element_id: never_expire
        when: not password_will_expire

      - active_directory.users.set_password_never_expires:
        load:
          distinguishedName: new_user.distinguishedName
          domain_controller: domain_controller
        when: not password_will_expire

      - ppa.ui.output_progress:
          text: Set password to never expire
          percent: 100
          element_id: never_expire
        when: not password_will_expire


  - name: Ask Set Manager
    actions:

      - ppa.ui.input_confirm:
          text: Set the user's manager?
        save: set_manager


  - name: Select Manager
    when: set_manager
    while:
      name: manager_confirmed
      value: false
      restart: restart
    actions:

      - active_directory.users.get_interactive:
          title: Search for Manager
        load:
          domain_controller: domain_controller
        save: manager

      - ppa.ui.output_markdown:
          doc: >
            The manager for **{{ cn }}** will be set to **{{ manager.cn }}**.

      - ppa.ui.input_confirm:
          text: Is this correct?
        save: confirm

      - ppa.ui.output_error:
          text: Please select the manager again.
        when: not confirm
      
      - set:
          name: manager_confirmed
          value: true
        when: confirm


  - name: Set Manager
    when: set_manager
    actions:

      - ppa.ui.output_progress:
          text: Setting user's manager...
          element_id: set_manager

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

      - ppa.ui.output_progress:
          text: Set user's manager
          percent: 100
          element_id: set_manager


  - name: Ask Add To Groups
    actions:

      - ppa.ui.input_confirm:
          text: Add the user to groups?
        save: add_to_groups


  - name: Audit Groups
    when: add_to_groups
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Group Search


            PPA will audit groups from Active Directory & ask you to make a selection.


            You can narrow the audit down to an Organizational Unit if required.

      - ppa.ui.input_confirm:
          text: Please choose an option
          confirm: Choose Organizational Unit
          cancel: Get All Groups
        save: search

      - active_directory.organizational_units.select_one:
          text: Select an Organizational Unit
        load:
          organizational_units: all_organizational_units
        save: search_scope
        when: search

      - ppa.ui.output_progress:
          text: Getting groups from Active Directory...
          percent: null
          element_id: getting_groups

      - active_directory.groups.get_all:
        load:
          search_base: search_scope.distinguishedName
          domain_controller: domain_controller
        save: groups
        when: search

      - active_directory.groups.get_all:
        load:
          domain_controller: domain_controller
        save: groups
        when: not search

      - ppa.ui.output_progress:
          text: Got {{ groups | length }} groups from Active Directory
          percent: 100
          element_id: getting_groups


  - name: Select Group(s)
    when: add_to_groups
    while:
      name: groups_confirmed
      value: false
    actions:

      - active_directory.groups.select:
          text: Select Groups
          minimum: 1
        load:
          groups: groups
        save: group_selection

      - active_directory.groups.display:
          text: Selected Groups
        load:
          groups: group_selection.all

      - ppa.ui.input_confirm:
          text: Are these groups correct?
        save: groups_confirmed


  - name: Add To Group(s)
    when: add_to_groups
    actions:

      - ppa.ui.output_progress:
          text: Adding user to {{ group_selection.total }} group(s)...
          percent: null
          element_id: add_to_groups

      - active_directory.users.add_to_group:
        load:
          user_distinguishedName: new_user.distinguishedName
          group_distinguishedName: group.distinguishedName
          domain_controller: domain_controller
        for_each:
          items: group_selection.all
          name: group

      - ppa.ui.output_progress:
          text: Successfully added user to {{ group_selection.total }} group(s)
          percent: 100
          element_id: add_to_groups


  - name: New User Summary
    actions:

      - active_directory.users.by_samaccountname:
        load:
          sAMAccountName: new_user.sAMAccountName
          domain_controller: domain_controller
        save: updated_user

      - ppa.ui.output_markdown:
          doc: >
            ## Summary


            ### New User Details


            **Logon Name:** {{ updated_user.sAMAccountName }}


            **Full Name:** {{ updated_user.cn }}


            **Email Address:** {{ updated_user.mail or '_not supplied_' }}


            **Manager:** {{ manager.cn if set_manager else '_not supplied_' }}


            **Description:** {{ updated_user.description or '_not supplied_' }}


            **Enabled:** {{ updated_user.is_enabled }}


            **Password Will Expire:** {{ password_will_expire }}


            **Directory Location:** {{ updated_user.distinguishedName }}

            {% if password_will_expire %}

              _The user's password will need to be changed on first logon._

            {% else %}

              _The user's password **will not** need to be changed on first logon as they have a non-expiring password._

            {% endif %}

            ### Group Memberships

            {% if group_selection %}

            {% for group in group_selection.all %}

            - {{ group.cn }}

            {% endfor %}

            {% else %}

            The user was not added to any groups.

            {% endif %}

      - ppa.ui.input_accept:
          text: Show Password

      - ppa.ui.output_markdown:
          doc: >
            **Password:** `{{ new_password }}`
          sensitive: true

      - ppa.ui.output_error:
          text: Store this password securely now! It will not be visible when the task finishes.

      - ppa.ui.input_accept:
          text: Done
Running this Playbook

Click download playbook
Import the playbook on the Playbooks page in PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab
Integrations

PPA User Interface
Hashicorp Vault Key-Value engine
Active Directory Users & Groups
Required Vault Details

Active Directory
IP/DNS address of a Domain Controller
Domain FQDN
Username
Password
The Active Directory credentials need permission to create a user & add them to groups.
Vault Configuration Wizard

The first time you run a task built from this playbook, PPA will check the required Vault details exist.
If they don't exist, PPA will ask you to supply the details at the start of the task.
Below you can see a user providing details the first time they run an Active Directory task.
vault-config-wizard
Once the details are added to Vault, the task won't ask for them again.
If you don't know the required details, ask an administrator to run the task or configure Vault manually.
What the Task Does

Once started, this task allows the operator to:
Provide new user details
Choose the Organizational Unit to create the user in
Set the user's password
Choose one or more Security Groups to add the user to
See our other playbooks
Get PPA for free!

Start automating your estate with a free 30 day trial today. No signup required!
Get PPA Express
Documentation

Installation Guide
See how easy it is to get started with our installation guide
Playbooks
View our task writing reference guide
Plugins
See how to integrate with different systems using our plugins reference guide.