Edit

Share via

New-EntraInvitation

  • Reference
Module:
Microsoft.Graph.Entra

This cmdlet is used to invite a new external user to your directory.

Syntax

New-EntraInvitation
   [-InvitedUser <User>]
   [-InvitedUserType <String>]
   -InvitedUserEmailAddress <String>
   [-SendInvitationMessage <Boolean>]-InviteRedirectUrl <String>
   [-InvitedUserMessageInfo <InvitedUserMessageInfo>]
   [-InvitedUserDisplayName <String>]
   [<CommonParameters>]

Description

This cmdlet is used to invite a new external user to your directory.

Invitation adds an external user to the organization. When creating a new invitation, you have several options available:

  • On invitation creation, Microsoft Graph can automatically send an invitation email directly to the invited user, or your app can use the inviteRedeemUrl returned in the response to craft your own invitation (through your communication mechanism of choice) to the invited user. If you decide to have Microsoft Graph send an invitation email automatically, you can specify the content and language of the email by using invitedUserMessageInfo.

  • When the user is invited, a user entity (of userType Guest) is created and can be used to control access to resources. The invited user has to go through the redemption process to access any resources they have been invited to.

To reset the redemption status for a guest user, the User.ReadWrite.All permission is the minimum required.

For delegated scenarios, the signed-in user must have at least one of the following roles: Guest Inviter, Directory Writers, or User Administrator. Additionally, to reset the redemption status, the signed-in user must have the Helpdesk Administrator or User Administrator role.

Examples

Example 1: Invite a new external user to your directory

Connect-Entra -Scopes 'User.Invite.All'
$params = @{
    InvitedUserEmailAddress = 'someexternaluser@externaldomain.com'
    SendInvitationMessage = $True
    InviteRedirectUrl = 'https://myapps.onmicrosoft.com'
}

New-EntraInvitation @params

Id                                   InviteRedeemUrl
--                                   ---------------
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3dd5aec55f-2d12-4442-8d2f-cc…

This example sent an email to the user who's email address is in the -InvitedUserEmailAddress parameter.

When the user accepts the invitation, they're forwarded to the url as specified in the -InviteRedirectUrl parameter.

  • -SendInvitationMessage Parameter indicates whether or not an invitation message will be sent to the invited user.

Example 2: Invite a new external user to your directory with InvitedUserDisplayName parameter

Connect-Entra -Scopes 'User.Invite.All'
$params = @{
    InvitedUserEmailAddress = 'someexternaluser@externaldomain.com'
    SendInvitationMessage = $True
    InviteRedirectUrl = 'https://myapps.onmicrosoft.com'
    InvitedUserDisplayName = 'microsoftuser'
}

New-EntraInvitation @params

Id                                   InviteRedeemUrl
--                                   ---------------
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3dd5aec55f-2d12-4442-8d2f-cc…

This example demonstrates how to invite a new external user to your directory with -InvitedUserDisplayName parameter.

  • -InvitedUserEmailAddressParameter specifies the Email address to which the invitation is sent.
  • -SendInvitationMessage Parameter indicates whether or not an invitation message will be sent to the invited user
  • -InviteRedirectUrl Parameter specifies The URL to which the invited user is forwarded after accepting the invitation.
  • -InvitedUserDisplayNameParameter specifies the display name of the user.

Example 3: Invite a new external user to your directory with InvitedUserMessageInfo parameter

Connect-Entra -Scopes 'User.Invite.All'
$a= New-Object Microsoft.Open.MSGraph.Model.InvitedUserMessageInfo
$a.CustomizedMessageBody = 'Hi there, how are you'
$a.MessageLanguage = 'EN'
$params = @{
    InvitedUserEmailAddress = 'someexternaluser@externaldomain.com'
    SendInvitationMessage = $True
    InviteRedirectUrl = 'https://myapps.microsoft.com'
    InvitedUserMessageInfo = $a
}

New-EntraInvitation @params

Id                                   InviteRedeemUrl
--                                   ---------------
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3dd5aec55f-2d12-4442-8d2f-cc…

This example demonstrates how to invite a new external user to your directory with InvitedUserMessageInfo parameter.

  • -InvitedUserEmailAddressParameter specifies the Email address to which the invitation is sent.
  • -SendInvitationMessage Parameter indicates whether or not an invitation message will be sent to the invited user.
  • -InviteRedirectUrl Parameter specifies The URL to which the invited user is forwarded after accepting the invitation.
  • -InvitedUserMessageInfoParameter specifies addition information to specify how the invitation message is sent.

Example 4: Invite a new external user to your directory with InvitedUserType parameter

Connect-Entra -Scopes 'User.Invite.All'
$params = @{
    InvitedUserEmailAddress = 'someexternaluser@externaldomain.com'
    SendInvitationMessage = $True
    InviteRedirectUrl = 'https://myapps.microsoft.com'
    InvitedUserType = 'Guest'
}

New-EntraInvitation @params

Id                                   InviteRedeemUrl
--                                   ---------------
9e2b9f02-c2cb-4832-920d-81959f44e397 https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitations.microsoft.com%2fredeem%2f%3ftenant%3dd5aec55f-2d12-4442-8d2f-cc…

This example demonstrates how to invite a new external user to your directory with InvitedUserType parameter.

Parameters

-InvitedUser

An existing user object in the directory that you want to add or update the B2B credentials for.

Type:User
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InvitedUserDisplayName

The display name of the user as it appears in your directory.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InvitedUserEmailAddress

The Email address to which the invitation is sent.

Type:System.String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-InvitedUserMessageInfo

Addition information to specify how the invitation message is sent.

Type:InvitedUserMessageInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InvitedUserType

The userType of the user being invited. By default, this is Guest.

You can invite as Member if you are company administrator.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InviteRedirectUrl

The URL to which the invited user is forwarded after accepting the invitation.

Type:System.String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-SendInvitationMessage

A Boolean parameter that indicates whether or not an invitation message sent to the invited user.

Type:System.Boolean
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

None

Outputs

System.Object

Notes