Password Expiration Audit

This is an interactive task that reports on Users in Active Directory whose passwords:

Have expired
Will expire in a given window

Playbook Files

This playbook was built for PPA version 3.3

plugins:
  active_directory: ^13.0
  hashicorp_vault: ^8.0
  ppa: ^11.4
  ppa_tools: ^11.0


set:
  all_users: []
  approaching_expiry: []
  password_expiries: []
  expired: []
  expiry_window: null
  expiry_window_key: null
  expiry_window_map:
    7 days: 7
    14 days: 14
    30 days: 30
    Custom: 0

steps:

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


            ### Active Directory - Password Expiration Report


            Use this task to view users in Active Directory whose passwords:


            - Have expired


            - Will expire in a given window


            You will need to:


            - Select which report(s) to generate


            - Choose whether to audit Users from Security Groups or Organizational Units


            __Note:__ auditing users from Organizational Units _is not_  recursive.

      - 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: Select Reports
    actions:
      - ppa.ui.input_choice:
          text: Select Reports
          options:
            - Expired Passwords
            - Passwords Approaching Expiry
            - Both Expired & Approaching Expiry
        save: selected_report

      - ppa.ui.input_choice:
          text: Select an expiry window
          options:
            - value: 7 days
              order: 1
            - value: 14 days
              order: 2
            - value: 30 days
              order: 3
            - value: Custom
              order: 4
        save: expiry_window_key
        when: selected_report in ['Passwords Approaching Expiry', 'Both Expired & Approaching Expiry']

      - ppa_tools.dictionaries.get:
        load:
          dictionary: expiry_window_map
          key: expiry_window_key
        save: expiry_window
        when: expiry_window_key is not None

      - ppa.ui.input_number:
          text: Number of days
        save: expiry_window
        when: expiry_window == 0

  - name: Choose Search Type
    actions:
      - ppa.ui.output_markdown:
          doc: >
            ### Finding Users


            Please choose whether you'd like to find users based on their:


            - Group Memberships

            - Organizational Unit

      - ppa.ui.input_choice:
          text: Audit Method
          options:
            - Group Memberships
            - Organizational Unit
        save: search_type


  - name: Get Groups (Group Membership Search)
    when: search_type == "Group Memberships"
    actions:
      - ppa.ui.output_markdown:
          doc: >
            ### Group Search


            Groups will now be audited from Active Directory.


            Please choose whether PPA should find:


            - _All_ Security Groups

            - Security Groups in an Organizational Unit

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

      - active_directory.organizational_units.get_all:
        load:
          domain_controller: domain_controller
        save: organizational_units
        when: get_in_ou

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

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

      - active_directory.groups.get_all:
        load:
          search_base: organizational_unit.distinguishedName
          domain_controller: domain_controller
        save: groups
        when: get_in_ou

      - active_directory.groups.select:
          text: Select Group(s)
          minimum: 1
        load:
          groups: groups
        save: group_selection


  - name: Get Users From Groups (Group Membership Search)
    when: search_type == "Group Memberships"
    for_each:
      items: group_selection.all
      name: group
    actions:
      - ppa.ui.output_progress:
          text: Getting Users from {{ group_selection.total }} Security Groups...
          percent: null
          element_id: getting_users
        when: step_counter == 1

      - active_directory.groups.get_users:
        load:
          distinguishedName: group.distinguishedName
          domain_controller: domain_controller
        save: users

      - ppa_tools.lists.combine:
        load:
          first: all_users
          second: users
        save: all_users

      # Users in more than one of the selected groups will be duplicated, so remove them now.
      - ppa_tools.dictionaries.remove_duplicates:
          key: sAMAccountName
        load:
          items: all_users
        save: all_users

      - count:
        load:
          item: all_users
        save: user_count
        when: step_counter == group_selection.total

      - ppa.ui.output_progress:
          text: Got {{ user_count }} Users from {{ group_selection.total }} Security Groups
          percent: 100
          element_id: getting_users
        when: step_counter == group_selection.total


  - name: Select Organizational Units (Organizational Unit Search)
    when: search_type == "Organizational Unit"
    actions:
      - active_directory.organizational_units.get_all:
        load:
          domain_controller: domain_controller
        save: organizational_units

      - active_directory.organizational_units.select:
          text: Select Organizational Units
          minimum: 1
        load:
          organizational_units: organizational_units
        save: organizational_unit_selection


  - name: Get Users (Organizational Unit Search)
    when: search_type == "Organizational Unit"
    for_each:
      items: organizational_unit_selection.all
      name: ou
    actions:

      - ppa.ui.output_progress:
          text: Getting Users from {{ organizational_unit_selection.total }} Organizational Units...
          percent: null
          element_id: getting_users
        when: step_counter == 1

      - active_directory.users.get_all:
          one_level: true
        load:
          search_base: ou.distinguishedName
          domain_controller: domain_controller
        save: users

      - ppa_tools.lists.combine:
        load:
          first: all_users
          second: users
        save: all_users

      - count:
        load:
          item: all_users
        save: user_count
        when: step_counter == organizational_unit_selection.total

      - ppa.ui.output_progress:
          text: Got {{ user_count }} Users from {{ organizational_unit_selection.total }} Organizational Units
          percent: 100
          element_id: getting_users
        when: step_counter == organizational_unit_selection.total


  - name: Exit If Too Many Users
    when: user_count > 10000
    actions:
      - ppa.ui.output_error:
          text: Found {{ user_count }} users across the selected {{ search_type }}.

      - ppa.ui.output_error:
          text: The task will take a long time to audit these users, & may time out.

      - ppa.ui.output_error:
          text: Please run the task against a smaller collection of users.

      - exit:
          exit_code: 2


  - name: Warn If Large Number Of Users
    when: user_count > 5000
    actions:
      - ppa.ui.output_error:
          text: Found {{ user_count }} users, the task may take a long time to run.

      - ppa.ui.input_confirm:
          text: Continue anyway?
        save: continue

      - ppa.ui.output_info:
          text: The task will not continue, goodbye!
        when: not continue

      - exit:
          exit_code: 0
        when: not continue


  - name: Audit Intro & Get Maximum Password Age
    actions:
      - ppa.ui.output_markdown:
          doc: >
            ### Password Expiry Audit


            PPA will now audit password expiry dates for each user.


            __Note:__ If a user's password is set to _never_ expire, it will be ignored.

      - ppa.ui.input_accept:
          text: Next

      - active_directory.domain.maximum_password_age:
        load:
          domain_controller: domain_controller
        save: maximum_password_age


  - name: Get User Password Expiries
    actions:

      - ppa.ui.output_progress:
          text: Getting password expiry details for each user...
          percent: null
          element_id: getting_all_expiries

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

      - debug:
          identifier: password_expiries

      - ppa.ui.output_progress:
          text: Got password expiry details for each user
          percent: 100
          element_id: getting_all_expiries


  - name: Start Next Progress Bar
    actions:
      - ppa.ui.output_progress:
          text: Generating selected report(s)...
          percent: null
          element_id: generating_reports


  - name: Generate Reports
    when: password_expiries
    for_each:
      items: all_users
      name: user
      skip: skip_user
    actions:

      - ppa_tools.lists.get_item:
        load:
          items: password_expiries
          index: step_index
        save: expiry
        when: password_expiries

      - log:
          message: "Expiry for {{ user.sAMAccountName }}: {{ expiry }}"

      - set:
          name: skip_user
          value: true
        when: not expiry

      #############################
      # Approaching Expiry Report #
      #############################

      - ppa_tools.lists.append:
          value:
            cn: '{{ user.cn }}'
            mail: '{{ user.mail }}'
            time_to_expiry: '{{ expiry.days }} days, {{ expiry.hours }} hrs, & {{ expiry.minutes }} mins'
        load:
          items: approaching_expiry
        save: approaching_expiry
        # Has an expiry, expiry days is less than selected window, and it hasn't already expired.
        when: selected_report != 'Expired Passwords' and expiry and expiry.days < expiry_window and expiry.total_seconds > 0

      ##################
      # Expired Report #
      ##################

      - ppa_tools.lists.append:
          value:
            cn: '{{ user.cn }}'
            mail: '{{ user.mail }}'
            expired_at: '{{ expiry.timestamp }}'
        load:
          items: expired
        save: expired
        # Has an expiry, expiry days is less than selected window, and it hasn't already expired.
        when: selected_report != 'Passwords Approaching Expiry' and expiry and expiry.total_seconds < 0


  - name: Close Current & Start Next Progress Bar
    actions:
      - ppa.ui.output_progress:
          text: Generated the selected report(s)
          percent: 100
          element_id: generating_reports


  - name: Display Approaching Expiry
    when: selected_report in ['Passwords Approaching Expiry', 'Both Expired & Approaching Expiry']
    actions:
      - ppa.ui.output_info:
          text: Found no users with passwords expiring in the next {{ expiry_window }} days.
        when: not approaching_expiry

      - active_directory.users.output_custom_table:
          text: Passwords Expiring Within {{ expiry_window }} Days
          header:
            - Common Name
            - Email Address
            - Time To Expiry
          attributes:
            - cn
            - mail
            - time_to_expiry
        load:
          users: approaching_expiry
        when: approaching_expiry

      - ppa.ui.input_accept:
          text: Next
        when: selected_report == 'Both Expired & Approaching Expiry'


  - name: Display Expired
    when: selected_report != 'Passwords Approaching Expiry'
    actions:

      - ppa.ui.output_info:
          text: Found no users with expired passwords.
        when: not expired

      - active_directory.users.output_custom_table:
          text: Expired Passwords
          header:
            - Common Name
            - Email Address
            - Expired At
          attributes:
            - cn
            - mail
            - expired_at
        load:
          users: expired
        when: expired

      - 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

Large Numbers of Users

While this task will run against up to 10,000 Users, we recommend sticking to no more than 5,000 at a time for performance reasons.

Integrations

PPA User Interface
Hashicorp Vault Key-Value engine
Active Directory Users, Groups, Organizational Units, & Domain

Required Vault Details

Active Directory

IP/DNS address of a Domain Controller
Domain FQDN
Username
Password

The Active Directory credentials require permission to audit Users.

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:

Select which report(s) to generate
Choose whether to audit Users from Security Groups or Organizational Units
Pick the relevant objects to audit Users from

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.