在 Microsoft Teams 中從使用者檢視移除外部聊天 (系統管理員)
身為租使用者系統管理員,您可以使用新的RemoveAllAccessForUser圖形 API,從使用者的檢視中移除由外部啟動的聊天。
Microsoft Teams 系統管理員可能需要移除由組織外部人員建立的使用者聊天。 例如,您的其中一個使用者可能收到來自公司外部人員的聊天要求。 該聊天可能包含不當或惡意的內容,而且身為系統管理員,您可以移除該聊天來協助保護您的使用者。
若要使用 RemoveAllAccessForUser 圖形 API,您必須提供三個參數:tenantId、userId和chatsId/threadId。 tenantId是 Teams 租使用者的唯一識別碼。 userId是您要移除聊天的唯一識別碼。 chatsId/threadId是您要從中移除使用者的 Teams 聊天對話的唯一識別碼。
您可以從新整合稽核記錄 (外部使用者與租使用者中的使用者通訊時產生的 UAL) 事件取得這三個參數。 UAL 事件包含寄件者、收件者、聊天對話和訊息的相關資訊。 您可以使用 UAL 事件來識別您要撤銷存取權的聊天對話,然後從活動詳細資料中擷取 tenantId、 userId和 chatsId/threadId 。
使用 RemoveAllAccessForUser 圖形 API 的步驟
- 步驟 1:搜尋符合您準則 的 UAL 事件 。 如果您想要尋找將使用者新增至聊天的所有事件,您可以在搜尋查詢中使用「MemberAdded」事件。
- 步驟 2:從 UAL 事件詳細資料中解壓縮tenantId、userId和chatsId/threadId
- 步驟 3:使用所需的參數呼叫 RemoveAllAccessForUser 圖形 API
步驟 1:搜尋符合您準則的 UAL 事件
若要搜尋符合準則的 UAL 事件,您可以使用 Search-UnifiedAuditLog 圖形 API,或使用Microsoft Purview 合規性入口網站中的稽核記錄搜尋功能。 本檔其餘部分假設您使用的是Microsoft Purview 合規性入口網站中的互動式版本。 請使用下列步驟:
https://compliance.microsoft.com以全域系統管理員或稽核記錄管理員的身分登入。
在左側導覽中,選取 [稽核]。
在 [稽核記錄] 搜尋頁面上,指定下列準則:
- 在 [稽核] 頁面上,選取 [搜尋]。
- 活動:選取 [成員已加入 (],並選擇從 [活動 – 作業名稱] 欄位選取 [MessageReceived) ],然後選擇 [工作負載] 的[MicrosoftTeams]。
- 日期範圍:選取涵蓋外部使用者與租使用者中的使用者通訊時段的日期範圍。 (選擇性) 使用者:在租使用者中輸入您感興趣之使用者的 UPN。
選取 [搜尋]。 這會排入搜尋佇列,以便在背景中執行。
完成後,請檢閱搜尋結果,並找出您感興趣的聊天和使用者所涉及的 UAL 事件, (下方的步驟 3) 。
步驟 2:從 UAL 事件詳細資料中解壓縮 tenantId、userId 和 chatsId/threadId
若要從 UAL 事件詳細資料擷取 tenantId、 userId和 chatsId/threadId ,您可以使用活動的 OrganizationId、 UserKey和 ChatThreadId 欄位。 如果您搜尋了 MemberAdded 事件,您可能會看到使用者新增至外部聊天的活動,以及您的使用者將外部使用者新增至聊天的位置。 您會想要在 [ 成員 詳細資料] 區段中尋找租使用者使用者的事件 (這表示這是已新增的使用者,請參閱) 下方的圖 2。 若要這樣做,請執行下列步驟:
選取其中一個涉及您要撤銷存取權之外部使用者的 UAL 事件。
在 [事件詳細資料] 窗格中:
- 複製 OrganizationId 字 段的值。 這是 Teams 租使用者的 租使用者標識 符。
- 複製 UserKey 欄位的值。 這是您租使用者中已新增至聊天之使用者的 userId 。
- 複製 [ChatThreatId] 欄位的值。 這是訊息所屬之 Teams 聊天對話的 聊天Id/threadId 。
請參閱下列螢幕擷取畫面,顯示 Purview 搜尋結果詳細資料的範例:
圖 1 (UAL MemberAdded 事件的詳細資料)
圖 2 (MemberAdded UAL 事件) 成員詳細資料
步驟 3:使用所需的參數呼叫 RemoveAllAccessForUser 圖形 API
若要使用參數呼叫 RemoveAllAccessForUser 圖形 API,您必須針對圖形 API 使用 HTTP POST 要求:
POST https://graph.microsoft.com/beta/chats/{chatsId}/removeAllAccessForUser
將 {chatsId} 取代為您要採取行動的聊天 標識 符。 要求內文應包含具有下列屬性的 JSON 使用者 物件:
- tenantId:Teams 租使用者的租使用者識別碼。
- 識別碼:您要從租使用者中移動聊天之使用者的使用者識別碼。
例如,要求看起來可能像這樣:
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"
}
}
若要驗證要求,您必須在 [授權] 標題中提供有效的存取權杖。 存取權杖應具有 Chat.ReadWrite.All 許可權。 若要取得存取權杖,您可以使用 Azure AD OAuth 2.0 端點。 如需詳細資訊,請參閱 Microsoft Graph - 代表使用者取得存取權。
如果要求成功,回應的狀態碼為「204 無內容」和空白內文。 如果要求失敗,回應會出現錯誤碼和訊息,說明失敗的原因。
有許多方法可以呼叫 Microsoft 圖形 API – 如果您不熟悉如何執行此動作,建議您從像Graph Explorer這樣的互動式工具開始。 有些系統管理員會建立應用程式,或使用 PowerShell 與圖形 API 互動。
範例代碼
下列 PowerShell 程式碼可以做為起點。 此代碼會顯示如何取得使用者權杖、建立具有必要許可權的用戶端應用程式,以及如何使用該用戶端應用程式呼叫圖形 API移除郵件。
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