Password Reset

This is an interactive task for resetting a user's password in Active Directory.

The user will be forced to reset their password on next logon.

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


set:
  accepted: false


steps:


  - name: Greeting
    actions:

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


            ### Active Directory - Password Reset


            Use this task to reset the password of an Active Directory user.


            You will need to:


            - Search for & select the Active Directory user

            - Select a password generation method

            - Choose whether the user's password should be changed on next logon


      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

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


  - name: Search for Active Directory User
    actions:

      - active_directory.users.get_interactive:
        load:
          domain_controller: domain_controller
        save: active_directory_user


  - name: Choose Password Generation Method
    actions:

      - ppa.ui.input_choice:
          text: Select a Password Method
          options:
            - Supply Manually
            - Dictionary Words
            - Random Characters
        save: generator


  - name: Set Password (Dictionary Words)
    when: generator == "Dictionary Words"
    while:
      name: dictionary_complete
      value: false
    actions:

      - set:
          name: accepted
          value: true

      - ppa_tools.password_generators.dictionary_words_interactive:
          length: 20
          word_count: 4
          format: mixed
          sensitive: true
        save: password

      - ppa.ui.output_progress:
          text: Setting new password...
          element_id: set_password_dictionary_{{ step_counter }}

      - active_directory.users.set_password:
        load:
          password: password
          distinguishedName: active_directory_user.distinguishedName
          domain_controller: domain_controller
        rescue:

          - ppa.ui.output_progress:
              text: New password not accepted by Active Directory
              percent: 0
              element_id: set_password_dictionary_{{ step_counter }}
            when: rescue.type == "InvalidPassword"

          - ppa.ui.output_error:
              text: The password did not meet Active Directory complexity requirements.
            when: rescue.type == "InvalidPassword"

          - ppa.ui.output_error:
              text: This password method may not be suitable for the domain.
            when: rescue.type == "InvalidPassword"

          - set:
              name: accepted
              value: false
            when: rescue.type == "InvalidPassword"

          - ppa.ui.input_confirm:
              text: Would you like to use a different password method?
            save: dictionary_complete
            when: rescue.type == "InvalidPassword"

          - ppa.ui.output_progress:
              text: Failed to set new password
              percent: 0
              element_id: set_password_dictionary_{{ step_counter }}
            when: rescue.type != "InvalidPassword"

          - ppa.ui.output_error:
              text: "Failed to set new password: {{ rescue.error }}"
            when: rescue.type != "InvalidPassword"

          - exit:
              exit_code: 2
            when: rescue.type != "InvalidPassword"

      - ppa.ui.output_progress:
          text: New password set successfully
          percent: 100
          element_id: set_password_dictionary_{{ step_counter }}
        when: accepted

      - set:
          name: dictionary_complete
          value: true
        when: accepted


  - name: Switch Password Generator If Dictionary Words Failed
    when: not accepted and generator == "Dictionary Words"
    actions:

      - ppa.ui.input_choice:
          text: Select a Password Method
          options:
            - Supply Manually
            - Random Characters
        save: generator


  - name: Set Password (Random Characters)
    when: generator == "Random Characters"
    while:
      name: random_complete
      value: false
    actions:

      - set:
          name: accepted
          value: true

      - ppa_tools.password_generators.regex:
          length: 20
        save: password

      - ppa.ui.output_progress:
          text: Setting new password...
          element_id: set_password_random_{{ step_counter }}

      - active_directory.users.set_password:
        load:
          password: password
          distinguishedName: active_directory_user.distinguishedName
          domain_controller: domain_controller
        rescue:

          - ppa.ui.output_progress:
              text: New password not accepted by Active Directory
              percent: 0
              element_id: set_password_{{ step_counter }}
            when: rescue.type == "InvalidPassword"

          - ppa.ui.output_error:
              text: The password did not meet Active Directory complexity requirements.
            when: rescue.type == "InvalidPassword"

          - set:
              name: accepted
              value: false
            when: rescue.type == "InvalidPassword"

          - ppa.ui.output_progress:
              text: Failed to set new password
              percent: 0
              element_id: set_password_random_{{ step_counter }}
            when: rescue.type != "InvalidPassword"

          - ppa.ui.output_error:
              text: "Failed to set new password: {{ rescue.error }}"
            when: rescue.type != "InvalidPassword"

          - exit:
              exit_code: 2
            when: rescue.type != "InvalidPassword"

      - ppa.ui.output_progress:
          text: New password set successfully
          percent: 100
          element_id: set_password_random_{{ step_counter }}
        when: accepted

      - set:
          name: random_complete
          value: true
        when: accepted


  - name: Set Password (Supply Manually)
    when: generator == "Supply Manually"
    actions:

      - active_directory.users.set_password_interactive:
        load:
          distinguishedName: active_directory_user.distinguishedName
          domain_controller: domain_controller
        save: password


  - name: Force Change On Next Logon
    actions:

      - ppa.ui.input_confirm:
          text: Force password change on next logon?
        save: force_password_change

      - ppa.ui.output_info:
          text: The user's password will not need to be changed on first logon.
        when: not force_password_change

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

      - active_directory.users.force_password_change:
        load:
          distinguishedName: active_directory_user.distinguishedName
          domain_controller: domain_controller
        when: force_password_change

      - ppa.ui.output_progress:
          text: Forced password change on next logon
          percent: 100
          element_id: force_password_change
        when: force_password_change


  - name: Summary
    actions:

      - ppa.ui.output_markdown:
          doc: >
            ### Password Reset Successful


            **User:** {{ active_directory_user.sAMAccountName }}

            {% if generator == "Supply Manually" %}

            **Password Method:** supplied manually

            {% else %}

            **Password Method:** {{ generator | lower }} generator

            {% endif %}

            The user's password {{ '_will_' if force_password_change else '_will not_' }} need to be changed on next logon.

      - ppa.ui.input_accept:
          text: Show New Password

      - ppa.ui.output_markdown:
          doc: >
            **Password:** `{{ 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 set a user's password.

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:

Search for & select an Active Directory user
Supply & confirm the user's new password

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.