Gerenciar contas de convidado usando Microsoft Entra PowerShell

As contas de convidado em Microsoft Entra ID permitem que usuários externos acessem recursos específicos, como arquivos, equipes ou sites sem serem membros completos da sua organização. Essas contas normalmente são usadas para colaboração com parceiros, empreiteiros ou clientes que precisam de acesso temporário aos recursos da sua organização.

Gerenciar contas de convidado efetivamente é crucial para manter a segurança e a integridade dos dados da sua organização. Como administrador, você precisa garantir que as contas de convidado recebam apenas as permissões necessárias e o acesso para executar suas tarefas pretendidas. Examinar e auditar regularmente essas contas também é importante para identificar quaisquer contas inativas ou expiradas que devem ser removidas. Este exercício não só ajuda a reduzir possíveis riscos de segurança, mas também garante o uso eficiente dos recursos da sua organização. Ao gerenciar bem as contas de convidado, você pode fornecer um ambiente seguro e produtivo para colaboração externa.

Prerequisites

Para gerenciar usuários convidados com Microsoft Entra PowerShell, você precisa:

Uma conta de usuário do Microsoft Entra. Se você ainda não tem uma conta, é possível criar uma conta gratuita.
Uma das seguintes funções:
Módulo do PowerShell do Microsoft Entra instalado. Siga o guia Instalar o módulo Microsoft Entra PowerShell para instalar o módulo.

Convidar contas de usuário convidado

Você pode convidar usuários convidados para sua organização usando Microsoft Entra PowerShell. Esse processo permite que usuários externos acessem recursos específicos em sua organização sem serem membros completos. Você pode convidar um único usuário convidado ou convidar vários usuários convidados ao mesmo tempo.

Convidar uma única conta de usuário convidado

Para convidar um único usuário convidado para sua organização com pelo menos a função Emissor do Convite ao Convidado.

# Connect to Microsoft Entra
Connect-Entra -Scopes 'User.Invite.All'

#Invite the guest user
New-EntraInvitation `
    -InvitedUserEmailAddress 'guestUser@contoso.com' `
    -InviteRedirectUrl 'https://contoso.com' `
    -SendInvitationMessage $true `
    -InvitedUserDisplayName 'Guest User'

Este script envia um convite para um usuário convidado com o endereço de e-mail guestUser@contoso.com, direcionando-o para https://contoso.com após a aceitação. A saída a seguir mostra os detalhes do usuário convidado.

Id                                   InviteRedeemUrl
--                                   ---------------                                           
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitation…

Convidar contas de usuários convidados em lote

Para convidar usuários convidados em massa para sua organização:

Preparar o arquivo CSV

Em Microsoft Excel, crie um arquivo CSV com a lista de nomes de usuário convidados e endereços de email. Certifique-se de incluir os títulos das colunas Nome e Email.

Por exemplo, crie uma planilha no seguinte formato:

Nome Email

Reed Smith rsmith@contoso.com

Hayden Cook hcook@fabricam.com

Isabel Garcia igarcia@contoso.com

Nome	Email
Reed Smith	rsmith@contoso.com
Hayden Cook	hcook@fabricam.com
Isabel Garcia	igarcia@contoso.com

Salve o arquivo como C:\BulkInvite\Invitations.csv ou qualquer local de sua escolha.

Se você não tiver Excel, poderá criar um arquivo CSV em qualquer editor de texto, como o Bloco de Notas. Separe cada valor com uma vírgula e cada linha com uma nova linha.

Conecte-se ao Microsoft Entra com pelo menos a função Emissor do Convite ao Convidado.

Connect-Entra -Scopes 'User.Invite.All'

# Import the CSV file containing the invitations.
$invitations = Import-Csv -Path "c:\bulkinvite\invitations.csv"

# Define the message to be sent to the invited users.
$messageBody = "Hello. You are invited to the Contoso organization."

# Iterate over each invitation in the CSV file.
foreach ($invitation in $invitations) {
    # Define the invitation parameters
    $invitationParams = @{
        InvitedUserEmailAddress = $invitation.Email  # Ensure this matches your CSV column name
        InviteRedirectUrl       = "https://contoso.com"
        SendInvitationMessage   = $true
        InvitedUserMessageInfo  = @{
            CustomizedMessageBody = $messageBody
        }
    }

    # Create a new invitation using the defined parameters
    New-EntraInvitation @invitationParams
}

Esse script importa uma lista de convites de um arquivo CSV. Define uma mensagem personalizada para os usuários convidados e, em seguida, percorre cada convite para enviar um convite a cada usuário usando seu endereço de e-mail.

A saída a seguir mostra os detalhes dos usuários convidados.

Id                                   InviteRedeemUrl
--                                   ---------------                                                      
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitation…
bbbbbbbb-1111-2222-3333-cccccccccccc https://login.microsoftonline.com/redeem?rd=https%3a%2f%2finvitation…

Exibir e exportar contas de usuário convidado

Para exibir e exportar usuários convidados:

Conecte-se ao Microsoft Entra com pelo menos a função Emissor do Convite ao Convidado.

Connect-Entra -Scopes 'User.Read.All'
 

# Retrieve all guest user accounts.
Get-EntraUser -Filter "userType eq 'Guest'" -All -Property "displayName", "mail", "createdDateTime", "AccountEnabled" | Select-Object "displayName", "mail", "createdDateTime", "AccountEnabled"

O script recupera todas as contas de usuário convidado de Microsoft Entra ID com seus nomes de exibição, endereços de email e datas de criação e exibe a lista desses usuários convidados.

DisplayName   Id   Mail                               createdDateTime      AccountEnabled
-----------   --   ----                               ---------------      --------------
externaluser1      externaluser1@externaldomain1.com  13/09/2024 18:37:33  True
externaluser2      externaluser2@externaldomain2.com  15/02/2024 15:05:31  True

Gerenciar o patrocínio de usuário convidado

Em Microsoft Entra ID, o patrocínio de convidados permite designar usuários ou grupos específicos como patrocinadores para usuários convidados, dando a eles a capacidade de gerenciar o acesso e as permissões do usuário convidado. Esse recurso é útil para organizações que desejam controlar e monitorar o acesso de usuários externos.

Para gerenciar o patrocínio de usuário convidado, você pode atribuir, exibir e remover um patrocinador de um usuário convidado. Você precisa de pelo menos uma função de Administrador de Usuário para executar essas ações.

O exemplo a seguir mostra como atribuir um patrocinador a um usuário convidado em Microsoft Entra ID. Você pode usar o New-EntraUserSponsor cmdlet para atribuir um patrocinador a um usuário convidado especificado.

Connect-Entra -Scopes 'User.ReadWrite.All'

$sponsor = Get-EntraUser -UserId 'SponsorEmail@contoso.com'
Set-EntraUserSponsor -UserId 'guestuser@contoso.com' -Type User -SponsorIds $sponsor.Id

Este exemplo atribui um patrocinador a um usuário convidado em Microsoft Entra ID. O UserId parâmetro especifica o usuário convidado e o SponsorId parâmetro especifica o patrocinador.

Exibir os patrocinadores de um usuário convidado

O exemplo a seguir mostra como exibir os patrocinadores de um usuário convidado no Microsoft Entra ID. Você pode usar o Get-EntraUserSponsor cmdlet para recuperar os patrocinadores de um usuário convidado especificado.

Connect-Entra -Scopes 'User.Read.All'

Get-EntraUserSponsor -UserId 'guestuser@contoso.com' -All | Select-Object Id, DisplayName, '@odata.type', CreatedDateTime | Format-Table -AutoSize

Este exemplo recupera os patrocinadores de um usuário convidado em Microsoft Entra ID. O UserId parâmetro especifica o usuário convidado.

id                                   displayName          @odata.type           createdDateTime
--                                   -----------      -----------           ---------------
aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb GuestUser Sponsor 1  #microsoft.graph.user 5/6/2025 11:29:26 PM
bbbbbbbb-1111-2222-3333-bbbbbbbbbbbb GuestUser Sponsor 2  #microsoft.graph.user 5/6/2025 11:29:27 PM

O exemplo a seguir mostra como remover um patrocinador de um usuário convidado em Microsoft Entra ID. Você pode usar o Remove-EntraUserSponsor cmdlet para remover um patrocinador de um usuário convidado especificado.

Connect-Entra -Scopes 'User.ReadWrite.All'

$sponsor = Get-EntraUserSponsor -UserId 'SawyerM@contoso.com' | Where-Object { $_.displayName -eq 'Adele Vance (Fabrikam)' }
Remove-EntraUserSponsor -UserId 'SawyerM@Contoso.com' -SponsorId $sponsor.Id

Este exemplo remove um patrocinador de um usuário convidado no Microsoft Entra ID. O UserId parâmetro especifica o usuário convidado e o SponsorId parâmetro especifica o patrocinador a ser removido.

Redefinir o status de resgate do usuário convidado

Em Microsoft Entra ID, a redefinição do status de resgate de um usuário convidado é necessária quando você deseja permitir que o usuário resgate o convite novamente. Esse recurso será útil se o usuário não concluir o processo de resgate ou se seu status precisar ser redefinido por qualquer motivo. O exemplo a seguir demonstra como redefinir o status de resgate para um usuário convidado enviando-lhes um novo convite.

Primeiro identifique o usuário convidado e envie um novo convite: isso redefine o status de resgate convidando o usuário convidado novamente.

Connect-Entra -Scopes 'User.Invite.All'

$user = Get-EntraUser -Filter "startsWith(mail, 'johndoe@gmail.com')"
New-EntraInvitation `
    -InvitedUserEmailAddress $user.Mail `
    -InviteRedirectUrl "https://myapps.contoso.com" `
    -ResetRedemption `
    -SendInvitationMessage `
    -InvitedUser $user

Desabilitar contas de usuário convidado

Os exemplos a seguir mostram como desabilitar contas de usuário convidado no Microsoft Entra ID. Você pode desabilitar uma única conta de convidado ou desabilitar todas as contas de convidado com base em seus requisitos.

Desabilitar uma única conta de usuário convidado

Para desabilitar uma única conta de usuário convidado:

Conecte-se ao Microsoft Entra com pelo menos uma função de Administrador de Usuário:

Connect-Entra -Scopes 'User.ReadWrite.All'
  
# Disable the guest user account.
Get-EntraUser -Filter "userType eq 'Guest' and mail eq 'guestUser@contoso.com'" | Set-EntraUser -AccountEnabled $false

Desabilitar todas as contas de usuário convidado

Execute o cmdlet a seguir para desabilitar todas as contas de usuário convidado.

Connect-Entra -Scopes 'User.ReadWrite.All'

# Disable the guest user account
Get-EntraUser | Where-Object { $_.UserType -eq 'Guest' } | Set-EntraUser -AccountEnabled $false

Exibir e exportar contas de usuário convidado expiradas

Para exibir e exportar contas de usuário convidado expiradas:

Expanda o exemplo anterior para recuperar usuários convidados e verificar cada um deles quanto à expiração. Neste exemplo, presumimos que as contas de convidado expirem 90 dias após a criação.

$report = @() 
$now = Get-Date  
# Retrieve all guest users.
$guestUsers = Get-EntraUser -Filter "userType eq 'Guest'" -All

foreach ($guest in $guestUsers) {
    # Calculate the expiration date based on the creation date
    $guestExpirationDate = $guest.CreatedDateTime.AddDays(90)

    # Check if the account is expired
    if ($guestExpirationDate -lt $now) {
        # Add expired guest account details to the report
        $report += [PSCustomObject]@{
            Id          = $guest.Id
            Name        = $guest.DisplayName
            Mail        = $guest.Mail
            Expiration  = $guestExpirationDate
            CreatedDate = $guest.CreatedDateTime
        }
    }
}

Exporte o relatório para um arquivo CSV.

   $report | Export-Csv -Path "ExpiredGuestAccounts.csv" -NoTypeInformation

Remover contas de usuário convidado expiradas

Conecte-se ao Microsoft Entra com pelo menos uma função de Administrador de Usuário:

Neste exemplo, presumimos que as contas de convidado expirem 90 dias após a criação.

Note

Esse script remove todos os usuários convidados cujas contas expiraram. Essa ação é irreversível e deve ser usada com cuidado. Sempre verifique se você tem um backup ou um plano de recuperação em vigor antes de remover contas de usuário.

Connect-Entra -Scopes "User.ReadWrite.All"

$age = (Get-Date).AddDays(-90).ToString("yyyy-MM-ddTHH:mm:ssZ") 
Get-EntraUser -Filter "userType eq 'Guest' and createdDateTime le $age" -All | Remove-EntraUser

Comentários

Esta página foi útil?

Last updated on 2026-07-08