New-MgmtGraphUser

MgmtGraph: Creates a new Microsoft Graph user account

Script

#Requires -Version 5.1
#Requires -Modules Microsoft.Graph.Users

[CmdletBinding()]
Param (
    [Parameter(Mandatory = $true)]
    [string]$DisplayName,

    [Parameter(Mandatory = $true)]
    [string]$UserPrincipalName,

    [Parameter(Mandatory = $true)]
    [string]$MailNickname,

    [Parameter(Mandatory = $true)]
    [System.Security.SecureString]$Password,

    [bool]$AccountEnabled = $false,

    [string]$GivenName,

    [string]$Surname,

    [string]$JobTitle,

    [string]$Department
)

Process {
    try {
        $plainPassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Password))

        $params = @{
            'DisplayName'       = $DisplayName
            'UserPrincipalName' = $UserPrincipalName
            'MailNickname'      = $MailNickname
            'AccountEnabled'    = $AccountEnabled
            'PasswordProfile'   = @{ 'Password' = $plainPassword; 'ForceChangePasswordNextSignIn' = $true }
            'ErrorAction'       = 'Stop'
        }

        if ($GivenName) { $params.Add('GivenName', $GivenName) }
        if ($Surname) { $params.Add('Surname', $Surname) }
        if ($JobTitle) { $params.Add('JobTitle', $JobTitle) }
        if ($Department) { $params.Add('Department', $Department) }

        $user = New-MgUser @params
        
        $result = [PSCustomObject]@{
            DisplayName       = $user.DisplayName
            UserPrincipalName = $user.UserPrincipalName
            Id                = $user.Id
            AccountEnabled    = $user.AccountEnabled
            Status            = "UserCreated"
            Timestamp         = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
        }

        Write-Output $result
    }
    catch {
        throw
    }
}

Customize

DisplayName string

Specifies the display name for the user.

UserPrincipalName string

Specifies the UserPrincipalName (e.g., user@domain.com) for the user.

MailNickname string

Specifies the mail alias for the user.

Password System.Security.SecureString

Specifies the initial password for the user as a SecureString.

AccountEnabled bool

If set to $true, the account will be enabled upon creation. Defaults to $false.

GivenName string

Optional. Specifies the user's first name.

Surname string

Optional. Specifies the user's last name.

JobTitle string

Optional. Specifies the user's job title.

Department string

Optional. Specifies the user's department.