Create User

This is an interactive task for:

Creating a new Azure AD user
Adding them to groups (optional)
Assigning licences to them (optional)

The user's password is generated automatically & displayed with the new joiner information at the end.

Playbook Files

This playbook was built for PPA version 3.3

plugins:
  azure_ad: ^2.0
  ppa: ^11.4
  ppa_tools: ^11.0
  hashicorp_vault: ^8.0
  microsoft_graph: ^6.0


set:
  domain: null
  region: GB
  # There are default values that get updated by the task.
  successful_group_memberships: []
  disabled_plans: {}


steps:

  - name: Check Domain
    when: not domain
    actions:

      - ppa.ui.output_error:
          text: The Azure AD domain is not configured in the playbook.

      - ppa.ui.output_markdown:
          doc: |+
            Please add your domain to line 9 of the playbook:


            ```yaml
            domain: your-domain.com
            ```

      - ppa.ui.input_confirm:
          text: Would you like to supply a domain for this task run?
        save: supply_domain

      - ppa.ui.input_text:
          text: Domain
        save: domain
        when: supply_domain

      - exit:
          exit_code: 2
        when: not supply_domain


  - name: Greeting
    actions:

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


            ### Azure AD - Create User


            Use this task to create a new Azure AD user.


            You will need to:


            - Supply user details


            - Select groups to add them to (optional)


            - Assign licences & service plans (optional)

      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: azure
          keys:
            - name: tenant_id
            - name: client_id
            - name: client_secret
              sensitive: true
          reason: Getting Azure AD details
          create_missing: true
        save: graph_client


  - name: Provide User Details
    while:
      name: details_confirmed
      value: false
      restart: name_taken
    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: logon_name
                title: Logon Name - Optional (defaults to 'firstname.lastname')
                required: false
            - choice:
                name: force_password_change
                title: Force Password Change on First Logon
                options:
                  - Yes
                  - No
                default: Yes
        save: user_data

      - ppa_tools.text.to_bool:
        load:
          text: user_data.force_password_change
        save: force_password_change

      - set:
          name: logon_name
          value: "{{ user_data.first_name | lower }}.{{ user_data.last_name | lower }}"
        when: user_data.logon_name == ""

      - set:
          name: logon_name
        load:
          value: user_data.logon_name
        when: user_data.logon_name != ""

      - set:
          name: user_principal_name
          value: "{{ logon_name }}@{{ domain }}"

      - set:
          name: display_name
          value: "{{ user_data.first_name | title }} {{ user_data.last_name | title }}"

      - ppa.ui.output_progress:
          text: Checking logon name is available...
          element_id: check_name_available_{{ step_counter }}

      - azure_ad.users.get_free_principal_name:
          user_principal_names:
            - "{{ user_principal_name }}"
        load:
          client: graph_client
        save: available_name

      - ppa.ui.output_progress:
          text: Logon name is not available
          percent: 0
          element_id: check_name_available_{{ step_counter }}
        when: not available_name

      - ppa.ui.output_error:
          text: Principal name {{ user_principal_name }} is taken, please supply a different logon name.
        when: not available_name

      - ppa.ui.input_accept:
          text: OK
        when: not available_name

      - set:
          name: name_taken
          value: true
        when: not available_name

      - ppa.ui.output_progress:
          text: Logon name is available
          percent: 100
          element_id: check_name_available_{{ step_counter }}
        when: available_name

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


            **First Name:** {{ user_data.first_name }}


            **Last Name:** {{ user_data.last_name }}


            **Principal Name:** {{ user_principal_name }}


            **Location:** {{ region }}


            {% if force_password_change %}

            The user must change their password on first logon.

            {% else %}

            The user will not need to change their password on first logon.

            {% endif %}

      - ppa.ui.input_confirm:
          text: Create new user with these details?
        save: details_confirmed

      - ppa.ui.output_error:
          text: Please provide the details again.


  - name: Create User
    actions:

      - ppa_tools.password_generators.from_policy:
          policy:
            lower: 5
            upper: 5
            digit: 5
            symbol: 5
        save: password

      - ppa.ui.output_progress:
          text: Creating new user...
          element_id: creating_user

      - azure_ad.users.create:
          display_name: "{{ display_name }}"
        load:
          force_password_change: force_password_change
          mail_nickname: logon_name
          password: password
          user_principal_name: user_principal_name
          client: graph_client

      - azure_ad.users.update:
          attributes:
            usageLocation: "{{ region }}"
        load:
          user_principal_name: user_principal_name
          client: graph_client

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


  - name: Get New User
    actions:

      - ppa_tools.timing.visual_countdown:
          doc: >
            Waiting for the new user to appear in Azure AD.
          refresh_interval: 1
          seconds: 5

      - ppa.ui.output_progress:
          text: Getting new user from Azure AD...
          element_id: get_user

      - azure_ad.users.get_by_principal_name:
        load:
          user_principal_name: user_principal_name
          client: graph_client
        save: created_user

      - ppa.ui.output_progress:
          text: Got new user from Azure AD
          percent: 100
          element_id: get_user


  - name: Ask Add To Groups
    actions:

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


  - name: Get Groups
    when: add_to_groups
    actions:

      - ppa.ui.output_progress:
          text: Getting groups from Azure AD...
          element_id: get_groups

      - azure_ad.security_groups.get_all:
        load:
          client: graph_client
        save: groups

      - ppa.ui.output_progress:
          text: Got {{ groups | length }} groups from Azure AD
          percent: 100
          element_id: get_groups


  - name: Select Groups
    when: add_to_groups
    while:
      name: groups_confirmed
      value: false
      restart: select_again
    actions:

      - set:
          name: select_again
          value: false

      - azure_ad.security_groups.select:
          text: Select group(s)
        load:
          groups: groups
        save: group_selection

      - ppa.ui.output_error:
          text: No groups were selected.
        when: group_selection.total == 0

      - ppa.ui.input_confirm:
          text: Select groups again?
        save: select_again
        when: group_selection.total == 0

      - ppa.ui.output_error:
          text: The groups step will be skipped.
        when: group_selection.total == 0 and not select_again

      - set:
          name: groups_confirmed
          value: true
        when: group_selection.total == 0 and not select_again

      - azure_ad.security_groups.display:
          text: Selected Groups
        load:
          groups: group_selection.all
        when: group_selection.total > 0

      - ppa.ui.input_confirm:
          text: Are these groups correct?
        save: groups_confirmed
        when: group_selection.total > 0


  - name: Add To Groups
    when: add_to_groups and group_selection.total > 0
    for_each:
      items: group_selection.all
      name: group
    actions:

      - set:
          name: added
          value: true

      - ppa.ui.output_progress:
          text: Adding user to {{ group_selection.total }} group(s)...
          element_id: adding_to_groups
        when: step_counter == 1

      - azure_ad.security_groups.add_member:
        load:
          member_id: created_user.id
          group_id: group.id
          client: graph_client
        rescue:

          - set:
              name: added
              value: false

          - ppa.ui.output_error:
              text: The user was not added to group '{{ group.display_name }}'.
            when: rescue.type == "UnsupportedOperation"

          - ppa.ui.output_error:
              text: "Failed to add the user to {{ group.display_name }}: {{ rescue.error }}"
            when: rescue.type != "UnsupportedOperation"

          - exit:
              exit_code: 1
            when: rescue.type != "UnsupportedOperation"

      - ppa_tools.lists.append:
        load:
          items: successful_group_memberships
          value: group
        save: successful_group_memberships
        when: added

      - ppa.ui.output_progress:
          text: Added user to {{ group_selection.total }} group(s)
          percent: 100
          element_id: adding_to_groups
        when: step_counter == group_selection.total


  - name: Ask Assign licences
    actions:

      - ppa.ui.input_confirm:
          text: Assign licence(s)?
        save: assign_licences

      - set:
          name: licence_selection
          value:
            all: []
            first: null
            last: null
            total: 0


  - name: Get licences
    when: assign_licences
    actions:

      - ppa.ui.output_progress:
          text: Getting available licences...
          element_id: get_licences

      - azure_ad.licences.get_all:
        load:
          client: graph_client
        save: licences

      - ppa.ui.output_progress:
          text: Got available licences
          percent: 100
          element_id: get_licences


  - name: Select licences
    when: assign_licences
    while:
      name: licences_confirmed
      value: false
      restart: select_again
    actions:

      - set:
          name: select_again
          value: false

      - azure_ad.licences.select:
          text: Select licence(s) to assign
        load:
          licences: licences
        save: licence_selection

      - ppa.ui.output_error:
          text: No licences were selected.
        when: licence_selection.total == 0

      - ppa.ui.input_confirm:
          text: Select licences again?
        save: select_again
        when: licence_selection.total == 0

      - ppa.ui.output_error:
          text: The licence step will be skipped.
        when: licence_selection.total == 0 and not select_again

      - set:
          name: assign_licences
          value: false
        when: licence_selection.total == 0 and not select_again

      - set:
          name: licences_confirmed
          value: true
        when: licence_selection.total == 0 and not select_again

      - azure_ad.licences.display:
          text: Selected licence(s)
        load:
          licences: licence_selection.all
        when: licence_selection.total > 0

      - ppa.ui.input_confirm:
          text: Are these licence(s) correct?
        save: licences_confirmed
        when: licence_selection.total > 0


  - name: Ask Disable Service Plans
    when: licence_selection.total > 0
    actions:

      - ppa.ui.input_confirm:
          text: Disable service plans for any licences?
        save: disable_plans


  - name: Select licences To Modify
    when: licence_selection.total > 0 and disable_plans
    actions:

      - ppa.ui.output_info:
          text: Please select all licences you would like to disable service plans for.

      - ppa.ui.input_accept:
          text: OK

      - azure_ad.licences.select:
          text: Select licence(s)
        load:
          licences: licence_selection.all
        save: licences_to_modify

      - ppa.ui.output_error:
          text: No service plans will be modified for any licence.
        when: licences_to_modify.total == 0

      - ppa.ui.input_accept:
          text: OK
        when: licences_to_modify.total == 0

      - set:
          name: disable_plans
          value: false
        when: licences_to_modify.total == 0


  - name: Select licences To Modify
    when: licence_selection.total > 0 and disable_plans and licences_to_modify.total > 0
    for_each:
      items: licences_to_modify.all
      name: licence
      skip: skip
    actions:

      - ppa_tools.dictionaries.filter_from_list:
          filters:
            - key: applies_to
              type: not_equal
              value: user
        load:
          dictionaries: licence.service_plans
        save: user_service_plans

      - azure_ad.service_plans.select:
          text: >
            {{ licence.part_number | replace("_", " ")}} - Select Service Plan(s) to Disable
        load:
          service_plans: user_service_plans
        save: service_plan_selection

      - ppa.ui.output_error:
          text: No service plans will be disabled for this licence.
        when: service_plan_selection.total == 0

      - ppa.ui.output_info:
          text: >
            {{ service_plan_selection.total }} service plan(s) will be disabled for this licence.
        when: service_plan_selection.total > 0

      - ppa.ui.input_accept:
          text: OK

      - ppa_tools.dictionaries.insert:
        load:
          name: licence.part_number
          value: service_plan_selection.all
          dictionary: disabled_plans
        save: disabled_plans


  - name: Assign licence(s)
    when: licence_selection.total > 0
    for_each:
      items: licence_selection.all
      name: current_licence
    actions:

      - ppa_tools.dictionaries.get:
        load:
          key: current_licence.part_number
          dictionary: disabled_plans
        save: plans_to_disable
        when: disable_plans

      - set:
          name: plans_to_disable
          value: []
        when: not disable_plans

      - ppa.ui.output_progress:
          text: Assigning licence {{ current_licence.part_number | replace("_", " ") }}...
          element_id: assign_{{ step_counter }}
        when: plans_to_disable == []

      - ppa.ui.output_progress:
          text: Assigning licence {{ current_licence.part_number | replace("_", " ") }} with {{ plans_to_disable | length }} disabled plan(s)...
          element_id: assign_{{ step_counter }}
        when: plans_to_disable != []

      - azure_ad.licences.assign_to_user:
        load:
          sku_id: current_licence.sku_id
          user_principal_name: user_principal_name
          client: graph_client
          disabled_plans: plans_to_disable

      - ppa.ui.output_progress:
          text: Assigned licence {{ current_licence.part_number | replace("_", " ") }} successfully
          percent: 100
          element_id: assign_{{ step_counter }}
        when: plans_to_disable == []

      - ppa.ui.output_progress:
          text: Assigned licence {{ current_licence.part_number | replace("_", " ") }} with {{ plans_to_disable | length }} disabled plan(s)
          percent: 100
          element_id: assign_{{ step_counter }}
        when: plans_to_disable != []


  - name: Summary
    actions:

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


            ### User Details


            **First Name:** {{ user_data.first_name }}


            **Last Name:** {{ user_data.last_name }}


            **Principal Name:** {{ user_principal_name }}


            **Location:** {{ region }}


            {% if force_password_change %}

            The user must change their password on first logon.

            {% else %}

            The user will not need to change their password on first logon.

            {% endif %}


            ### Group Memberships

            {% if add_to_groups and group_selection.total > 0 %}

            {% for group in successful_group_memberships %}

            - {{ group.display_name }}

            {% endfor %}

            {% else %}

            The user was not added to any groups.

            {% endif %}


            ### Licences

            {% if assign_licences and licence_selection.total > 0 %}

            {% for licence in licence_selection.all %}

            {% if disabled_plans.get(licence.part_number) %}

            **Part Number:** {{ licence.part_number | replace("_", " ") | title }} ({{ disabled_plans.get(licence.part_number) | length }} plan(s) disabled)

            {% else %}

            **Part Number:** {{ licence.part_number | replace("_", " ") | title }} (all plans enabled)

            {% endif %}

            {% endfor %}

            {% else %}

            The user was not assigned any licences.

            {% endif %}

      - ppa.ui.input_accept:
          text: Show 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

Required Configuration

Azure AD Domain

You will need to configure your Azure AD domain on line 9 of the playbook:

  domain: your-domain.com

Region

Configure the region for new users on line 13:

  usage_location: GB

The region should be an ISO country code & must be set for a user before licences can be assigned.

Integrations

PPA User Interface
Hashicorp Vault Key-Value engine
Microsoft Graph Users, Groups, & Licences

Required Vault Details

Azure AD

Azure Tenant ID
Client ID (the ID of the app registration in Azure)
Client Secret

The Azure AD credentials require the following permissions:

Directory.Read.All
User.ReadWrite.All

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:

Supply the new user's details
Select groups to add them to (if applicable)
Choose licences to assign to them (if applicable)

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.