在 Teams (系統管理員Microsoft中，從使用者的檢視移除外部聊天)

發行項
10/15/2024
適用於:

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 租使用者的 tenantId 。
- 複製 UserKey 欄位的值。此值是您租使用者中已新增至聊天之使用者的 userId 。
- 複製 [ChatThreatId] 字段的值。此值是訊息所屬之 Teams 聊天對話的 聊天Id/threadId 。

請參閱下列螢幕快照，顯示 Purview 搜尋結果詳細資料的範例：

圖 1 (UAL MemberAdded 事件的詳細數據)

Microsoft檢視成員詳細數據
圖 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

共用方式為