Remover uma conversa externa da vista de um utilizador no Microsoft Teams (administrador)
Como administrador inquilino, pode utilizar o novo API do Graph RemoveAllAccessForUser para remover uma conversa iniciada externamente da vista do utilizador.
Os administradores do Microsoft Teams poderão ter de remover as conversas de utilizador criadas por pessoas fora da sua organização. Por exemplo, um dos seus utilizadores recebeu um pedido de chat de alguém fora da sua empresa. Essa conversa pode conter conteúdo inapropriado ou malicioso e, enquanto administrador, pode remover essa conversa para ajudar a proteger o seu utilizador.
Para utilizar a API do Graph RemoveAllAccessForUser, tem de fornecer três parâmetros: o tenantId, o userId e o chatsId/threadId. O tenantId é o identificador exclusivo do seu inquilino do Teams. O userId é o identificador exclusivo do utilizador para o qual pretende remover a conversa. O chatsId/threadId é o identificador exclusivo do tópico de chat do Teams do qual pretende remover o utilizador.
Pode obter estes três parâmetros a partir dos novos eventos UAL (Unified Audit Log) que são gerados quando um utilizador externo comunica com um utilizador no seu inquilino. Os eventos UAL contêm informações sobre o remetente, o destinatário, o tópico de chat e a mensagem. Pode utilizar os eventos UAL para identificar o tópico de chat a partir do qual pretende revogar o acesso e, em seguida, extrair o tenantId, o userId e o chatsId/threadId dos detalhes do evento.
Passos para utilizar a API do Graph RemoveAllAccessForUser
- Passo 1: procure os eventos UAL que correspondem aos seus critérios. Se quiser localizar todos os eventos em que um utilizador foi adicionado a uma conversa, pode utilizar o evento "MemberAdded" na sua consulta de pesquisa.
- Passo 2: extrair o tenantId, o userId e o chatsId/threadId dos detalhes do evento UAL
- Passo 3: chamar o API do Graph RemoveAllAccessForUser com os parâmetros pretendidos
Passo 1: procurar eventos UAL
Para procurar eventos UAL específicos, pode utilizar a graph API do Search-UnifiedAuditLog ou pode utilizar a funcionalidade de pesquisa de registos de auditoria no portal de conformidade do Microsoft Purview. As instruções seguintes utilizam o portal de conformidade do Microsoft Purview. Execute os seguintes passos:
Inicie sessão como https://compliance.microsoft.com administrador de registos de auditoria.
No painel de navegação esquerdo, selecione Auditoria.
Na página Pesquisa de registos de auditoria, especifique os seguintes critérios:
- Na página Auditoria, selecione Procurar.
- Atividades: selecione MembroAdded (e opcionalmente MessageReceived) no campo Atividades – nomes de operações e escolha MicrosoftTeams para a Carga de Trabalho.
- Intervalo de datas: selecione um intervalo de datas que abranja o período de tempo em que o utilizador externo comunicou com o utilizador no seu inquilino. (opcional) Utilizadores: introduza o UPN do utilizador no seu inquilino no qual está interessado.
Selecione Pesquisar. Este comando coloca uma pesquisa em fila para ser executada em segundo plano.
Depois de concluído, reveja os resultados da pesquisa e identifique os eventos UAL que envolvem o chat e o utilizador em que está interessado (Passo 3 abaixo).
Passo 2: extrair o tenantId, o userId e o chatsId/threadId dos detalhes do evento UAL
Para extrair o tenantId, o userId e o chatsId/threadId dos detalhes do evento UAL, pode utilizar os campos OrganizationId, UserKey e ChatThreadId do evento. Se procurou o evento MemberAdded , poderá ver eventos em que os seus utilizadores foram adicionados a uma conversa externa e também onde os seus utilizadores adicionaram um utilizador externo a uma conversa. Localize os eventos em que o utilizador no seu inquilino se encontra na secção Detalhes dos membros (indica que este é o utilizador que foi adicionado ; veja a figura 2 abaixo). Para fazer isso, execute estas etapas:
Selecione um dos eventos UAL que envolvem o utilizador externo a partir do qual pretende revogar o acesso.
No painel Detalhes do evento:
- Copie o valor do campo OrganizationId . Este valor é o tenantId do seu inquilino do Teams.
- Copie o valor do campo UserKey . Este valor é o userId do utilizador no seu inquilino que foi adicionado ao chat.
- Copie o valor do campo ChatThreatId . Este valor é o chatsId/threadId do tópico de chat do Teams ao qual a mensagem pertence.
Veja a seguinte captura de ecrã a mostrar um exemplo de um detalhe do resultado da pesquisa do Purview:
Figura 1 (detalhes do evento UAL MemberAdded)
Figura 2 (detalhes dos membros do evento UAL MemberAdded)
Passo 3: chamar o API do Graph RemoveAllAccessForUser com os parâmetros pretendidos
Para chamar removeAllAccessForUser API do Graph com os parâmetros, tem de utilizar um pedido HTTP POST para a graph API:
POST https://graph.microsoft.com/beta/chats/{chatsId}/removeAllAccessForUser
Substitua {chatsId} pelo ID da conversa em que pretende agir. O corpo do pedido deve conter um objeto de utilizador JSON com as seguintes propriedades:
- tenantId: o tenantID do seu inquilino do Teams.
- ID: o userID do utilizador no seu inquilino do qual pretende mover a conversa.
Por exemplo, um pedido pode ter o seguinte aspeto:
POST https://graph.microsoft.com/beta/chats/19:7d8980.........f94061cf8c2@unq.gbl.spaces/removeAllAccessForUser
Content-Type: application/json
{
"user": {
"id" : "d864e79f-……..-0eeb4d61fdc2",
"tenantId": "2a690434-………-13600199a"
}
}
Para autenticar o pedido, tem de fornecer um token de acesso válido no cabeçalho Autorização. O token de acesso deve ter as permissões Chat.ReadWrite.All. Para obter o token de acesso, pode utilizar o ponto final Azure AD OAuth 2.0. Para obter mais informações, consulte Microsoft Graph – Obter acesso em nome de um utilizador.
Se o pedido for bem-sucedido, a resposta tem um código de status "204 Sem Conteúdo" e um corpo vazio. Se o pedido falhar, a resposta tem um código de erro e uma mensagem que explica o motivo da falha.
Existem várias formas de chamar um microsoft API do Graph – se não estiver familiarizado com o processo, comece com uma ferramenta interativa, como o Graph Explorer. Alguns administradores criam uma aplicação ou utilizam o PowerShell para interagir com as Graph APIs.
Código de Exemplo
O seguinte código do PowerShell pode ser utilizado como ponto de partida. Este código mostra como adquirir o token de Utilizador, criar uma Aplicação cliente que tenha as permissões necessárias e como utilizar essa Aplicação cliente para chamar o API do Graph para remover a mensagem.
param(
# Tenant id for the user whom the chat access is going to be removed
[Parameter(Mandatory=$true)]
[String]
$TenantId,
# User id for the user whom the chat access is going to be removed
[Parameter(Mandatory=$true)]
[String]
$UserId,
# Id of the chat that from which access will be removed
[Parameter(Mandatory=$true)]
[String]
$ThreadId
)
# These may not all be necessary in your environment
# Install Microsoft.Graph.Authentication module for all users (requires admin rights)
if (Get-Module -ListAvailable -Name Microsoft.Graph.Authentication) {
Write-Host "Microsoft.Graph.Authentication module found." -ForegroundColor "Green"
}
else {
Write-Host "Microsoft.Graph.Authentication module not found. Installing"
Install-Module Microsoft.Graph.Authentication -Scope AllUsers -Force
}
# Install Microsoft.Graph.Applications module for all users (requires admin rights)
if (Get-Module -ListAvailable -Name Microsoft.Graph.Applications) {
Write-Host "Microsoft.Graph.Applications module found." -ForegroundColor "Green"
}
else {
Write-Host "Microsoft.Graph.Application module not found. Installing"
Install-Module Microsoft.Graph.Applications -Scope AllUsers -Force
}
# Install MSAL.PS module for all users (requires admin rights)
if (Get-Module -ListAvailable -Name MSAL.PS) {
Write-Host "MSAL module found." -ForegroundColor "Green"
}
else {
Write-Host "MSAL module not found. Installing"
Install-Module MSAL.PS -Scope AllUsers -Force
}
# Connect to graph and verify that a client application exists for this purpose - if not, create one
Connect-MgGraph -Scopes "Application.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All"
# Get client app info
$App = Get-MgApplication -Filter "DisplayName eq 'RemoveAllAccessForUserApp'"
$createAppParams = @{
publicClient = @{
redirectUris = "https://login.microsoftonline.com/common/oauth2/nativeclient"
}
}
# If client app is not found. Create it
if ($null -eq $App)
{
Write-Host "Client app not found. Creating new one." -ForegroundColor "Yellow"
$App = New-MgApplication -DisplayName 'RemoveAllAccessForUserApp' @createAppParams
Write-Host "Client app created. Waiting for 5 seconds before continuing." -ForegroundColor "Yellow"
Start-Sleep -Seconds 5
}
else
{
$AppId = $App.AppId
Write-Host "Client app with id '$AppId' found'" -ForegroundColor "Green"
}
$ClientId = $App.AppId
# Now that we have the ID for our client application, we can call the RemoveAccessForUser API...
# Msal parameters required to get access token.
$MsalParams = @{
ClientId = $ClientId
TenantId = $TenantId
Scopes = 'Chat.ReadWrite.All'
}
# Get access token, it will prompt for interactive login
$MsalResponse = Get-MsalToken @MsalParams
$AccessToken = $MsalResponse.AccessToken
# Request authorization header containing the access token
$AuthHeader = @{
Authorization = "Bearer $AccessToken"
}
# Request url
$apiUrl = "https://graph.microsoft.com/beta/chats/$ThreadId/removeAllAccessForUser"
# Prepare request body
$Body = @{
user = @{
id = "$UserId"
tenantId = "$TenantId"
}
}
$Body = $Body | ConvertTo-Json
# Execute request
Write-Host "Executing RemoveAllAccessForUser request."
try {
Invoke-RestMethod -Headers $AuthHeader -Uri $apiUrl -Method POST -ContentType 'application/json' -Body $Body
Write-Host "Rquest to RemoveAllAccessForUser api succeeded." -ForegroundColor "Green"
} catch {
Write-Host "Request to RemoveAllAccessForUser api failed." -ForegroundColor "Red"
Write-Host "StatusCode:" $_.Exception.Response.StatusCode.value__
Write-Host "StatusDescription:" $_.Exception.Response.StatusDescription
$receiveStream = $_.Exception.Response.GetResponseStream();
Write-Host ([System.Text.Encoding]::ASCII).GetString($receiveStream.ToArray())
}
Write-Host "Disconnecting from Microsoft Graph!"
Disconnect-MgGraph