[範例] 匯出 Microsoft Entra ID 登入資訊

我們可能需要監控與分析 Microsoft Entra ID 的登入資訊, 但若需要不斷使用 Portal 下載可能十分麻煩。

除此之外, 剛好近期 Microsoft 想統一存取資料的套件 – Microsoft Graph, 因此我嘗試使用了新的 Microsoft Graph PowerShell 來取得 Microsoft Entra ID 的登入資訊。

本文將展示我所寫的 Microsoft Graph PowerShell 範例。

使用說明

範例使用的是帳號登入後取得, 並且帳號權限為全域管理員 (Global Administer), 權限可下修至僅取得 Microsoft Entra ID 登入資訊即可。

除此之外, 除了使用帳號登入外, 範例其實還能修改為使用應用程式驗證的方式進行登入取得資料, 官方範例內有而這裡將簡單顯示用法。

2023-07-28 補充: 使用 Microsoft Graph 取得 Sign In Log 需擁有 Azure Active Premium 系列授權才能使用。 參考連結

語法介紹

Microsoft Graph PowerShell 具有屬於自己的模組, 因此我們需要安裝該模組, 並且模組適用於 PowerShell 5.1 或 PowerShell 7。

以下主要是判斷 Microsoft Graph PowerShell 之模組是否存在, 若不存在將進行安裝。

if (Get-Module -ListAvailable -Name Microsoft.Graph)
    {
        Write-Host "Module exists."
    }
    else
    {
        Write-Host "Module does not exist and Install Module."

        Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
        Install-Module Microsoft.Graph -Scope CurrentUser -Force
    }

確認模組安裝後我們即可進行登入。

登入過程中 Microsoft Graph PowerShell 比較特別的地方為需要設定存取資料的範圍。

因此需要取得登入資訊的我們需要使用者與稽核的讀取範圍權限, 如下語法:

Connect-MgGraph -Scopes "User.ReadWrite.All", "AuditLog.Read.All"

完成登入後, 我們即可使用 「Get-MgAuditLogSignIn -All」 取得登入資訊

Get-MgAuditLogSignIn -All

完成取得資料後即可中斷連線

Disconnect-MgGraph

補充說明

取得的資料部分需延伸使用才能取得完整的資訊, 若我們取得的第一層資訊是:

AppDisplayName
AppId, 
AppliedConditionalAccessPolicies, 
ClientAppUsed, 
ConditionalAccessStatus, 
CorrelationId, 
CreatedDateTime, 
DeviceDetail, (HasExpend)
IPAddress, 
Id, 
IsInteractive, 
Location, (HasExpend)
ResourceDisplayName, 
ResourceId, 
Status, (HasExpend)
UserDisplayName, 
UserId, 
UserPrincipalName, 
AdditionalProperties, 
RiskDetail, 
RiskEventTypes, 
RiskEventTypesV2, 
RiskLevelAggregated, 
RiskLevelDuringSignIn, 
RiskState

若我們延伸 DetailDetail 時可取得:

Browser
DeviceId
DisplayName
IsCompliant
IsManaged
OperatingSystem
TrustType

Device 的 Display Name 需登記至使用者裝置內才能被紀錄, 若沒有登記將顯示空值

若我們延伸 Location 時可取得:

City
CountryOrRegion
State

若我們延伸 Status 時可取得:

AdditionalDetail
ErrorCode
FailureReason

原始碼

以下原始碼為取得 Microsoft Entra ID 登入資訊範例, 取得內容主要是取得一般我們常需要的內容。

而過程中含有驗證模組, 登入取得資料, 最後匯出至 CSV 並登出。

Function Check-Module() {
    if (Get-Module -ListAvailable -Name Microsoft.Graph)
    {
        Write-Host "Module exists."
    }
    else
    {
        Write-Host "Module does not exist and Install Module."

        Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
        Install-Module Microsoft.Graph -Scope CurrentUser -Force
    }
}

Check-Module

Connect-MgGraph -Scopes "User.ReadWrite.All", "AuditLog.Read.All"

$AuditLog = Get-MgAuditLogSignIn -All
$SignInLog = @()

Foreach ($Log in $AuditLog)
{
    $Row = "" | Select Id, UserId, UserDisplayName, UserPrincipalName, CreatedDateTime, IPAddress, CountryOrRegion, State, City, ClientAppUsed, OS, DeviceDisplayName, Browser, AppDisplayName, ResourceDisplayName, IsInteractive
    $Row.Id = $Log.Id
    $Row.UserId = $Log.UserId
    $Row.UserDisplayName = $Log.UserDisplayName
    $Row.UserPrincipalName = $Log.UserPrincipalName
    $Row.CreatedDateTime = $Log.CreatedDateTime
    $Row.IPAddress = $Log.IPAddress
    $Row.CountryOrRegion = $Log.Location.CountryOrRegion
    $Row.State = $Log.Location.State
    $Row.City = $Log.Location.City
    $Row.ClientAppUsed = $Log.ClientAppUsed
    $Row.OS = $Log.DeviceDetail.OperatingSystem
    $Row.DeviceDisplayName = $Log.DeviceDetail.DisplayName
    $Row.Browser = $Log.DeviceDetail.Browser
    $Row.AppDisplayName = $Log.AppDisplayName
    $Row.ResourceDisplayName = $Log.ResourceDisplayName
    $Row.IsInteractive = $Log.IsInteractive

    $SignInLog += $Row
}

$Date = Get-Date -Format "yyyyMMddHHmmss"
$SignInLog | Export-Csv -Path C:\SignInLog-$Date.csv

Disconnect-MgGraph

<#

Sign In Audit Log Information

All
---------------------------------------------------
AppDisplayName
AppId, 
AppliedConditionalAccessPolicies, 
ClientAppUsed, 
ConditionalAccessStatus, 
CorrelationId, 
CreatedDateTime, 
DeviceDetail, (HasExpend)
IPAddress, 
Id, 
IsInteractive, 
Location, (HasExpend)
ResourceDisplayName, 
ResourceId, 
Status, (HasExpend)
UserDisplayName, 
UserId, 
UserPrincipalName, 
AdditionalProperties, 
RiskDetail, 
RiskEventTypes, 
RiskEventTypesV2, 
RiskLevelAggregated, 
RiskLevelDuringSignIn, 
RiskState

DeviceDetail
---------------------------------------------------
Browser
DeviceId
DisplayName
IsCompliant
IsManaged
OperatingSystem
TrustType

Location
---------------------------------------------------
City
CountryOrRegion
State

Status
---------------------------------------------------
AdditionalDetail
ErrorCode
FailureReason

#>

參考連結

 

以上內容為我個人的見解, 並感謝您的閱讀, 謝謝

分級: 入門是認識, 基本是運用, 進階是混合結合
範本是已可下載或可使用的範例, 至於教程當然是學習的結晶