Using Invoke-MgGraphRequest to Create Microsoft 365 Users
This guide demonstrates how to use the Invoke-MgGraphRequest cmdlet in Microsoft Graph PowerShell to create users in Microsoft 365. Learn how to construct custom requests, define user properties, and handle API responses with practical examples.
Creating users in Microsoft 365 is a common administrative task. While there are dedicated cmdlets for user creation like New-MgUser, the Invoke-MgGraphRequest cmdlet provides a flexible alternative for scenarios where you might need to directly interact with Microsoft Graph API endpoints. This article will walk you through using Invoke-MgGraphRequest specifically for user creation, demonstrating various ways to create users with different levels of detail, including reading data from a CSV file.
Cmdlet Syntax for User Creation
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $Body- -Method: Specifies the HTTP method. For user creation, use POST.
- -Uri: The API endpoint for user creation (https://graph.microsoft.com/v1.0/users).
- -Body: Contains the user details in a hashtable format, which will be sent in the body of the request.
Usage Examples
Example 1: Creating a User with Basic Information
The following script creates a user with minimal required properties:
$Body = @{
accountEnabled = $true
displayName = "John Doe"
mailNickname = "johndoe"
userPrincipalName = "johndoe@yourdomain.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = "P@ssw0rd!"
}
}
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $Body
Example 2: Creating a User with Additional Properties
This example includes additional properties such as givenName, surname, jobTitle, and department to provide more detailed user information:
$Body = @{
accountEnabled = $true
displayName = "Jane Smith"
mailNickname = "janesmith"
userPrincipalName = "janesmith@yourdomain.com"
givenName = "Jane"
surname = "Smith"
jobTitle = "Marketing Manager"
department = "Marketing"
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = "P@ssw0rd!"
}
}
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $Body
Example 3: Creating Multiple Users
This script demonstrates how to create multiple users by looping through an array of user hashtables:
$Users = @(
@{
accountEnabled = $true
displayName = "Alice Johnson"
mailNickname = "alicejohnson"
userPrincipalName = "alicejohnson@yourdomain.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = "P@ssw0rd!"
}
}
@{
accountEnabled = $true
displayName = "Bob Roberts"
mailNickname = "bobroberts"
userPrincipalName = "bobroberts@yourdomain.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = "P@ssw0rd!"
}
}
)
foreach ($User in $Users) {
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $User
}
Example 4: Creating Users from a CSV File
The CSV file should have the following structure:
DisplayName,MailNickname,UserPrincipalName,Password
Alice Johnson,alicejohnson,alicejohnson@yourdomain.com,P@ssw0rd!
Bob Roberts,bobroberts,bobroberts@yourdomain.com,P@ssw0rd!
This script reads user data from a CSV file and creates users based on the information provided in the file:
$CSVFilePath = "C:\UsersToCreate.csv"
$Users = Import-Csv -Path $CSVFilePath
foreach ($User in $Users) {
$Body = @{
accountEnabled = $true
displayName = $User.DisplayName
mailNickname = $User.MailNickname
userPrincipalName = $User.UserPrincipalName
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = $User.Password
}
}
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body $Body
}
Cmdlet Tips
- API Version: Ensure that the API version (v1.0) used in the URI is the most stable version for production environments.
- Password Complexity: Make sure the passwords meet your organization's password policy to avoid errors during user creation.
- Batch Requests: For large-scale user creation, consider batching requests to avoid hitting rate limits.
Possible Errors & Solutions
Error: Authentication_RequestDenied
Cause: Insufficient permissions.
Solution: Ensure that the authenticated user has the necessary permissions such as User.ReadWrite.All.
Error: BadRequest_InvalidRequest
Cause: Incorrect or missing properties in the request body.
Solution: Verify that all required properties are correctly specified and that the JSON structure is valid.
Error: Request_UnsupportedQuery
Cause: Using unsupported parameters or incorrect URI.
Solution: Review the Microsoft Graph documentation to ensure you are using supported parameters and correct URI formats.
Error: Invoke-MgGraphRequest : A parameter cannot be found that matches parameter name 'BodyParameter'.
Cause: -BodyParameter payload is not supported for Invoke-MgGraphRequest cmdlet.
Solution: Just use -Body instead of -BodyParameter and the cmdlet will work.
Use Cases
- Bulk User Creation: Ideal for scenarios where you need to create a large number of users from an external data source like a CSV file.
- Custom User Properties: Useful when creating users with additional attributes that are not easily set using standard cmdlets.
Frequently Asked Questions
1. What is Invoke-MgGraphRequest used for?
Invoke-MgGraphRequest is a Microsoft Graph PowerShell cmdlet used to make custom REST API calls to Microsoft Graph, enabling operations like creating users, updating resources, and more.
2. How can I verify if a user was created successfully?
You can verify by retrieving the user’s details using their UserPrincipalName:
Get-MgUser -UserId "johndoe@domain.com"3. How can I create a user using Invoke-MgGraphRequest?
Use the following script to create a new user:
$Body = @{
accountEnabled = $true
displayName = "John Doe"
mailNickname = "johndoe"
userPrincipalName = "johndoe@domain.com"
passwordProfile = @{
forceChangePasswordNextSignIn = $true
password = "Password123!"
}
}
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/users" -Body ($Body | ConvertTo-Json -Depth 10)4. What permissions are required to create users using Invoke-MgGraphRequest?
You need the User.ReadWrite.All or Directory.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.
Conclusion
The Invoke-MgGraphRequest cmdlet offers flexibility when creating users in Microsoft 365, especially when dealing with complex scenarios or when standard cmdlets fall short. By following the examples and tips provided, you can efficiently create users with varying levels of detail, leveraging the full power of Microsoft Graph API.
Remember to handle errors appropriately and ensure your API calls are well-structured to avoid common pitfalls. With practice, this method can become a powerful addition to your M365 management toolkit.
Additional Resources:
Microsoft Graph PowerShell Module DocumentationMicrosoft Graph API Documentation
Related Articles:
Using Get-MgDirectoryRole in Graph PowerShellUsing Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell