Quickstart: Add a guest user with PowerShell
There are many ways you can invite external partners to your apps and services with Azure Active Directory B2B collaboration. In the previous quickstart, you saw how to add guest users directly in the Azure portal. You can also use PowerShell to add guest users, either one at a time or in bulk. In this quickstart, you’ll use the New-MgInvitation command to add one guest user to your Azure tenant.
If you don’t have an Azure subscription, create a free account before you begin.
Install the Microsoft Graph Identity Sign-ins module (Microsoft.Graph.Identity.SignIns) and the Microsoft Graph Users module (Microsoft.Graph.Users). You can use the
#Requires statement to prevent running a script unless the required PowerShell modules are met.
#Requires -Modules Microsoft.Graph.Identity.SignIns, Microsoft.Graph.Users
Get a test email account
You need a test email account that you can send the invitation to. The account must be from outside your organization. You can use any type of account, including a social account such as a gmail.com or outlook.com address.
Sign in to your tenant
Run the following command to connect to the tenant domain:
Connect-MgGraph -Scopes 'User.ReadWrite.All'
When prompted, enter your credentials.
Send an invitation
To send an invitation to your test email account, run the following PowerShell command (replace "John Doe" and email@example.com with your test email account name and email address):
New-MgInvitation -InvitedUserDisplayName "John Doe" -InvitedUserEmailAddress John@contoso.com -InviteRedirectUrl "https://myapplications.microsoft.com" -SendInvitationMessage:$true
The command sends an invitation to the email address specified. Check the output, which should look similar to the following example:
Verify the user exists in the directory
To verify that the invited user was added to Azure AD, run the following command (replace firstname.lastname@example.org with your invited email):
Get-MgUser -Filter "Mail eq 'John@contoso.com'"
Check the output to make sure the user you invited is listed, with a user principal name (UPN) in the format emailaddress#EXT#@domain. For example, john_contoso.com#EXTemail@example.com, where fabrikam.onmicrosoft.com is the organization from which you sent the invitations.
Clean up resources
When no longer needed, you can delete the test user account in the directory. Run the following command to delete a user account:
Remove-MgUser -UserId '<String>'
Remove-MgUser -UserId 'john_contoso.com#EXTfirstname.lastname@example.org'
Remove-MgUser -UserId '3f80a75e-750b-49aa-a6b0-d9bf6df7b4c6'
In this quickstart, you invited and added a single guest user to your directory using PowerShell. Next, learn how to invite guest users in bulk using PowerShell.
Submit and view feedback for