Quickstart: Add a guest user with PowerShell

Applies to: Workforce tenants External tenants (learn more)

There are many ways you can invite external partners to your apps and services with Microsoft Entra B2B collaboration. In the previous quickstart, you saw how to add guest users directly in the Microsoft Entra admin center. 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 Microsoft Entra tenant.

If you don’t have an Azure subscription, create a Trial before you begin.

Prerequisites

To complete the scenario in this quickstart, you need:

• A role that allows you to create users in your tenant directory, such as at least a Guest Inviter role or a User Administrator.
• 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.

Sign in to your tenant

Run the following command to connect to the tenant domain:

Connect-MgGraph -Environment China -ClientId 'YOUR_CLIENT_ID' -TenantId 'YOUR_TENANT_ID' -Scopes 'User.ReadWrite.All'

When prompted, enter your credentials.

Send an invitation

1. To send an invitation to your test email account, run the following PowerShell command (replace "Henry Ross" and henry@contoso.com with your test email account name and email address):

   New-MgInvitation -InvitedUserDisplayName "Henry Ross" -InvitedUserEmailAddress henry@contoso.com -InviteRedirectUrl "https://myapplications.windowsazure.cn" -SendInvitationMessage:$true
   

2. The command sends an invitation to the email address specified. Check the output, which should look similar to the following example:

   Id                                   InviteRedeemUrl                                                                                                   
   --                                   ---------------                                                                                                   
   00aa00aa-bb11-cc22-dd33-44ee44ee44ee https://login.partner.microsoftonline.cn/redeem?...
   

Verify the user exists in the directory

1. To verify that the invited user was added to Microsoft Entra ID, run the following command (replace henry@contoso.com with your invited email):

   Get-MgUser -Filter "Mail eq 'henry@contoso.com'"
   

2. 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, henry_contoso.com#EXT#@fabrikam.partner.onmschina.cn, where fabrikam.partner.onmschina.cn is the organization from which you sent the invitations.

   Id                                   DisplayName              Mail                           UserPrincipalName        
   --                                   -----------              ----                           -----------------               
   00aa00aa-bb11-cc22-dd33-44ee44ee44ee Henry Ross               henry@contoso.com              henry@contoso.com
   

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>'

For example:

Remove-MgUser -UserId 'henry_contoso.com#EXT#@fabrikam.partner.onmschina.cn'

or

Remove-MgUser -UserId '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'

Next steps

In this quickstart, you invited and added a single guest user to your directory using PowerShell. You can invite guest users in bulk using PowerShell.