Create User

This is an interactive task for:

Creating a new Office 365 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

Requires PPA version 2.10.0 or newer

plugins:
  ppa: ^6
  ppa_tools: ^6.2
  hashicorp_vault: ^5
  microsoft_graph: ^2.1


set:
  domain: null
  region: GB


steps:

  - name: Check Domain
    when: not domain
    actions:

      - ppa.ui.output_error:
          text: The Office 365 domain is not configured in the playbook.

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


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

      - exit:
          exit_code: 2


  - name: Greeting
    actions:

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


            ### Office 365 - Create User


            Use this task to create a new Office 365 user.


            You will need to:


            - Supply a first name, last name, & logon name


            - Pick groups to add them to (if applicable)


            - Pick licences to assign (if applicable)

      - ppa.ui.input_accept:
          text: Start


  - name: Get Secrets
    actions:

      - hashicorp_vault.key_value.read_secret_keys:
          secret: office_365
          keys:
            - name: tenant_id
            - name: client_id
            - name: client_secret
              sensitive: true
          reason: Getting Office 365 details
          create_missing: true
        save: graph_client


  - name: Provide First & Last Names
    while:
      name: details_confirmed
      value: false
      restart: name_taken
    actions:

      - set:
          name: name_taken
          value: false

      - ppa.ui.input_text:
          text: First Name
          required: true
        save: first_name

      - ppa.ui.input_text:
          text: Last Name
          required: true
        save: last_name

      - ppa.ui.input_text:
          text: Logon Name
          required: true
        save: logon_name

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

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

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

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

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

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


            **First Name:** {{ first_name }}


            **Last Name:** {{ last_name }}


            **Logon Name:** {{ user_principal_name }}


            {% 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

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

      - microsoft_graph.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 Office 365.
          refresh_interval: 1
          seconds: 5

      - ppa.ui.output_progress:
          text: Getting new user from Office 365...
          element_id: get_user

      - microsoft_graph.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 Office 365
          percent: 100
          element_id: get_user


  - name: Ask Add To Groups
    actions:

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


  - name: Get Groups
    when: add_to_groups
    actions:

      - ppa.ui.output_progress:
          text: Getting groups from Office 365...
          element_id: get_groups

      - microsoft_graph.groups.get_all:
        load:
          client: graph_client
        save: groups

      - ppa.ui.output_progress:
          text: Got {{ groups | length }} groups from Office 365
          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

      - microsoft_graph.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 or not select_again


  - name: Add To Groups
    when: add_to_groups and group_selection.total > 0
    actions:

      - ppa.ui.output_progress:
          text: Assigning user to {{ group_selection.total }} group(s)...
          element_id: adding_to_groups

      - microsoft_graph.groups.add_member:
        load:
          member_id: created_user.id
          group_id: group.id
          client: graph_client
        for_each:
          items: group_selection.all
          name: group

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


  - name: Ask Assign Licences
    actions:

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


  - name: Get Subscriptions
    when: assign_licences
    actions:

      - ppa.ui.output_progress:
          text: Getting available subscriptions...
          element_id: get_subscriptions

      - microsoft_graph.subscriptions.get_all:
        load:
          client: graph_client
        save: subscriptions

      - ppa.ui.output_progress:
          text: Got available subscriptions
          percent: 100
          element_id: get_subscriptions


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

      - set:
          name: select_again
          value: false

      - microsoft_graph.subscriptions.select:
          text: Select licence(s) to assign
        load:
          subscriptions: subscriptions
        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 licensing step will be skipped.
        when: licence_selection.total == 0 and not select_again

      - set:
          name: licences_confirmed
          value: true
        when: licence_selection.total > 0 or not select_again


  - name: Assign Licence(s)
    when: assign_licences and licence_selection.total > 0
    actions:

      - ppa.ui.output_progress:
          text: Assigning {{ licence_selection.total }} licence(s)...
          element_id: assigning_licences

      - microsoft_graph.subscriptions.assign_to_user:
        load:
          sku_id: licence.sku_id
          user_principal_name: user_principal_name
          client: graph_client
        for_each:
          items: licence_selection.all
          name: licence

      - ppa.ui.output_progress:
          text: Assigned {{ licence_selection.total }} licence(s) successfully
          percent: 100
          element_id: assigning_licences


  - name: Summary
    actions:

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


            ### User Details


            **First Name:** {{ first_name }}


            **Last Name:** {{ last_name }}


            **Logon Name:** {{ user_principal_name }}


            **Location:** {{ region }}


            **Password:** _{{ password }}_


            {% 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 group_selection.all %}

            - {{ 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 %}

            - {{ licence.part_number | replace("_", " ") | title }}

            {% endfor %}

            {% else %}

            The user was not assigned any licences.

            {% endif %}

Running this Playbook

Click download playbook
Import the downloaded file via the Playbooks page on PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab

* Requires PPA v2.9.x or newer

Required Configuration

Office 365 Domain

You will need to configure your Office 365 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, & Subscriptions

Required Vault Details

Office 365

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

The Office 365 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.