M365Corner

🔧 New: User Management Graph PowerShell Toolkit

Simplify user tasks like bulk creation, updates, password resets, deletions, license checks & more — all from one place.

🚀 Launch Toolkit
M365 PowerShell

New-MgUser: How to Create Microsoft 365 User Accounts with Graph PowerShell

This guide demonstrates how to use the New-MgUser cmdlet in Microsoft Graph PowerShell to create Microsoft 365 users. Learn how to set properties like display name, user principal name, and password with examples for single and bulk creation

The New-MgUser cmdlet in Microsoft Graph PowerShell is an essential tool for administrators to create new users in Microsoft 365. This cmdlet allows for detailed user profile customization, making it a versatile option for managing user accounts. In this article, we will explore the basics of the New-MgUser cmdlet, provide usage examples, address possible errors and solutions, and offer tips for effective use.


Cmdlet Syntax 

New-MgUser -DisplayName <String> -UserPrincipalName <String> -MailNickname <String> -PasswordProfile <PSObject> -AccountEnabled <Boolean>

Key Parameters

  • -DisplayName: This parameter specifies the display name of the new user. It is a descriptive name that is shown in the Microsoft 365 admin center and in the address book.
  • -UserPrincipalName: This parameter sets the user's principal name, which is the sign-in name for the user in the format username@domain.com. It must be unique within the organization.
  • -MailNickname: This parameter defines the mail alias or nickname for the user. It is used to generate the primary email address and must be unique within the organization.
  • -PasswordProfile: This parameter specifies the password profile for the new user. It includes the user's password and whether the user must change the password at the next sign-in. The PasswordProfile is provided as a hashtable with keys Password and ForceChangePasswordNextSignIn.
  • -AccountEnabled: This parameter indicates whether the user account is enabled ($true) or disabled ($false). By default, it is set to $true to enable the account.

Usage Examples


Basic User Creation

Creating user using only the basic user attributes like DisplayName, UserPrincipalName, MailNickname and Password.

New-MgUser -DisplayName "John Doe" -UserPrincipalName "john.doe@yourdomain.com" -MailNickname "john.doe" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled
PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet

Creating a User with Additional Profile Information

Adding additional user information like -Surname and -JobTitle.

New-MgUser -DisplayName "Jane Smith" -UserPrincipalName "jane.smith@yourdomain.com" -MailNickname "jane.smith" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -GivenName "Jane" -Surname "Smith" -JobTitle "Marketing Manager"
PowerShell command creating a new Microsoft 365 user using New-MgUser cmdlet with additional info.

Creating a User with Department and Office Location

Adding additional user information like -Department and -OfficeLocation details.

New-MgUser -DisplayName "Mark Johnson" -UserPrincipalName "mark.johnson@yourdomain.com" -MailNickname "mark.johnson" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -Department "Sales" -OfficeLocation "Building 1"
PowerShell command creating a new Microsoft 365 user using New-MgUser cmdlet with Department and Office Location attributes.

Creating a User with Mobile Phone and Other Contact Information

Adding additional user information like -MobilePhone and -BusinessPhones details.

New-MgUser -DisplayName "Alice Brown" -UserPrincipalName "alice.brown@yourdomain.com" -MailNickname "alice.brown" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -MobilePhone "+1234567890" -BusinessPhones @("+0987654321")
PowerShell command creating a new Microsoft 365 user using New-MgUser cmdlet with Mobile Phone and BusinessPhones attributes.

Creating a User with Usage Location and Preferred Language

Adding additional user information like -UsageLocation and -PreferredLanguage details.

New-MgUser -DisplayName "Tom Wilson" -UserPrincipalName "tom.wilson@yourdomain.com" -MailNickname "tom.wilson" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -UsageLocation "US" -PreferredLanguage "en-US"
PowerShell command creating a new Microsoft 365 user using New-MgUser cmdlet with Usage Location and Preferred Language attributes.

Bulk User Creation

This is particularly useful for onboarding large teams or migrating users from another system.


    $users = Import-Csv -Path "Users.csv"
    foreach ($user in $users) {
        $userParams = @{
        DisplayName     = $user.DisplayName
        UserPrincipalName = $user.UserPrincipalName
        MailNickname    = $user.MailNickname
        AccountEnabled  = $true
        PasswordProfile = @{
        Password = $user.Password
        ForceChangePasswordNextSignIn = $true
        }
     }
        New-MgUser -BodyParameter $userParams
    }

CSV File Structure:

CSV file structure for creating multiple users using New-MgUser cmdlet.

If the script is run directly or from a .ps1 file you should get the list of newly created users as the output.

PowerShell script creating multiple Microsoft 365 users from a CSV file using New-MgUser

Create a Disabled User Account (e.g., for Service Use)

Creates a user account that is initially disabled (often used for service-level identities or staged provisioning), with a password set but login prevented due to accountEnabled = $false.

$params = @{
  accountEnabled = $false
  displayName = "Service Account - No Login"
  mailNickname = "svcaccount1"
  userPrincipalName = "svcaccount1@yourdomain.com"
  usageLocation = "US"
  passwordProfile = @{
    forceChangePasswordNextSignIn = $false
    password = "S3cureTempP@ssword!"
  }
}

New-MgUser -BodyParameter $params
PowerShell script creating service accounts without login using New-MgUser

Cmdlet Tips

  • Ensure Required Parameters: Always provide the required parameters: DisplayName, UserPrincipalName, MailNickname, PasswordProfile, and AccountEnabled.
  • Use Secure Passwords: When setting the PasswordProfile, use a strong password and ensure ForceChangePasswordNextSignIn is set to $true for security.
  • Check Existing Users: Before creating a new user, verify that the UserPrincipalName is not already taken to avoid conflicts.
  • Update User Properties: Additional user properties can be updated after creation using the Update-MgUser cmdlet if needed.

Possible Errors & Solutions

Error Solution
Invalid PasswordProfile Object Ensure the PasswordProfile object is formatted correctly as a hashtable with the required properties.
UserPrincipalName Already Exists Ensure the UserPrincipalName is unique and not already in use.
Password Does Not Meet Requirements Ensure that the password meets the complexity requirements or the tenant password policy.
Invalid UPN Suffix Validate the UPN suffix before creating the user. Example: 
if ($validDomains -contains $upnSuffix) {
                                            New-MgUser -BodyParameter $userParams
                                        } else {
                                            Write-Error "Invalid UPN suffix: $upnSuffix"
                                        }


Frequently Asked Questions

  • What is New-MgUser used for?
    New-MgUser is a Microsoft Graph PowerShell cmdlet used to create user accounts in a Microsoft 365 tenant. It allows specifying properties like display name, user principal name, and password settings.
  • How can I create a single user using New-MgUser?
    Use the following script to create a user:
    $Body = @{
displayName = "John Doe"
userPrincipalName = "johndoe@domain.com"
mailNickname = "johndoe"
accountEnabled = $true
passwordProfile = @{
        forceChangePasswordNextSignIn = $true
        password = "StrongPassword123!"
    }
}
New-MgUser -BodyParameter $Body
  • Can I create multiple users using a CSV file?
    Yes, prepare a CSV file with the following format:
    DisplayName,UserPrincipalName,MailNickname,Password
John Doe,johndoe@domain.com,johndoe,StrongPassword123!
Jane Smith,janesmith@domain.com,janesmith,AnotherPassword123!
                            

    $Users = Import-Csv -Path "C:\Path\To\File.csv"
foreach ($User in $Users) {
    $Body = @{
        displayName = $User.DisplayName
        userPrincipalName = $User.UserPrincipalName
        mailNickname = $User.MailNickname
        accountEnabled = $true
        passwordProfile = @{
            forceChangePasswordNextSignIn = $true
            password = $User.Password
        }
    }
    New-MgUser -BodyParameter $Body
}
  • What permissions are required to create users?
    You need the User.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure delegated or application permissions are granted in Azure AD.
  • How to assign Department and office Location properties while creating user?
    You need to pass the -OfficeLocation and -Department parameters and their respective values
    New-MgUser -DisplayName "Mark Johnson" -UserPrincipalName "mark.johnson@yourdomain.com" -MailNickname "mark.johnson" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -Department "Sales" -OfficeLocation "Building 1"
  • How to assign Mobile Phone and Other Contact Information while creating Users?
    You need to pass the -MobilePhone and -BusinessPhones parameter (and their respective values) and other contact-related params.
    New-MgUser -DisplayName "Alice Brown" -UserPrincipalName "alice.brown@yourdomain.com" -MailNickname "alice.brown" -PasswordProfile @{Password="Password123"; ForceChangePasswordNextSignIn=$true} -AccountEnabled  -MobilePhone "+1234567890" -BusinessPhones @("+0987654321")
  • Why am I getting a "Bad Request" error when creating a new user with New-MgUser?
    This usually happens when required properties are missing or incorrectly formatted. Ensure that -PasswordProfile, -AccountEnabled, and -MailNickname are all specified correctly. Also, verify that the UserPrincipalName is unique and valid.
Required Properties for Creating a New User

To successfully create a user with New-MgUser, the following properties are mandatory:
  • DisplayName
  • UserPrincipalName
  • PasswordProfile
  • AccountEnabled
  • MailNickname
Omitting any of these will result in a 400 Bad Request or a validation error during user creation.
💡 Recommended: Use Hashtable for Consistency and Bulk Operations

While most user properties in New-MgUser can be passed directly, the passwordProfile must be provided as a nested hashtable. Using a hashtable via $params is the preferred approach — especially useful when automating or bulk-creating users. 

$params = @{
    accountEnabled = $true
    displayName = "Adele Vance"
    mailNickname = "adelev"
    userPrincipalName = "adelev@contoso.com"
    passwordProfile = @{
            forceChangePasswordNextSignIn = $true
            password = "Xw3lP@ssword!"
    }
}
New-MgUser -BodyParameter $params
This approach improves readability and scales better in scripts involving multiple users.
📎 Assign Licenses During User Creation (Optional Step)

You can simplify provisioning by assigning licenses immediately after creating a new user account. Use the Set-MgUserLicense cmdlet right after New-MgUser to activate services like Exchange, Teams, or SharePoint for the new user.

This step is optional but useful for automating onboarding workflows.
📌 Ensure Proper User Location for Compliance & Licensing

Setting the usageLocation property correctly is critical when creating users, as it determines what Microsoft 365 services are available in that region.

Incorrect or missing usageLocation can lead to license assignment errors or service restrictions.

Adding Microsoft 365 User Using Admin Center

  1. Login into Microsoft 365 Admin Center
    2. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet
  2. Select Users >> Active Users page. Click Add a User button.
    3. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet
  3. Enter basic user details like First name, Last name, Display Name etc.
    4. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet
  4. Select Product License and click Next option
    5. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet
  5. Select User Role and click Next option.
    6. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet
  6. Review the user details and click Finish adding button.
    7. PowerShell command creating a new Microsoft 365 user with New-MgUser cmdlet

Conclusion

The New-MgUser cmdlet is a powerful tool for creating new users in Microsoft 365. By understanding the syntax, leveraging various parameters, and addressing common errors, administrators can effectively manage user creation. Follow the examples and tips provided to enhance your user management process in Microsoft 365.


Suggested Reading

If You Prefer the Graph API Way

Note: User creation via Graph API requires a POST request to /users with mandatory fields such as accountEnabled, displayName, mailNickname, userPrincipalName, and passwordProfile. The payload must be passed in JSON format.

Create a Single User


    # Define the user object to be created
    $userPayload = @{
        accountEnabled    = $true
        displayName       = "John Sample"
        mailNickname      = "johnsample"
        userPrincipalName = "john.sample@yourtenant.onmicrosoft.com"
        passwordProfile   = @{
            forceChangePasswordNextSignIn = $true
            password = "Xyz@123456"
        }
    }

    # Convert to JSON and invoke Graph API
    Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body ($userPayload | ConvertTo-Json -Depth 10)

Create Users in Bulk from CSV


    # Sample CSV headers: displayName, mailNickname, userPrincipalName, password
    $users = Import-Csv -Path "C:\Users\admin\Documents\new-users.csv"

    foreach ($user in $users) {
        $userPayload = @{
            accountEnabled    = $true
            displayName       = $user.displayName
            mailNickname      = $user.mailNickname
            userPrincipalName = $user.userPrincipalName
            passwordProfile   = @{
                forceChangePasswordNextSignIn = $true
                password = $user.password
            }
        }

        # Create the user
        Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body ($userPayload | ConvertTo-Json -Depth 10)
    }
Note: Make sure the passwords in the CSV meet the organization’s password policy.

Required Permissions

To create users via the Graph API, you must have one of the following:

  • User.ReadWrite.All
  • Directory.ReadWrite.All

Graph API Documentation

👉 POST /users - Microsoft Graph v1.0
Table of Contents

X

Table of Contents

© m365corner.com. All Rights Reserved. Design by HTML Codex