トップ > Microsoft Entra ID > PowerShellコマンドでアクセスレビューを作成する

PowerShellコマンドでアクセスレビューを作成する

Microsoft Entra ID PowerShell

Teamsのチームを効率的に管理するために、Microsoft Entra管理センターからアクセスレビューを作成する方法について以下の記事でご紹介しました。
blog.jbs.co.jp
今回は、そのアクセスレビューをPowerShellコマンドから作成する方法をご紹介します。

前提

アクセスレビュー機能を利用する際には、アクセスレビューを作成する管理者とアクセスレビューの対象となるユーザー数分、以下ライセンスが必要となります。

  • Microsoft Entra ID P2（Microsoft 365 E5 ライセンスに含まれる）
  • Microsoft Entra ID Governance
    • Governanceライセンスについてはアクセスレビューの一部機能を利用する際に必要です。
    • Microsoft 365 E5 ライセンスを持っていることが前提となります。

また、今回はPowerShellからの操作になりますので、Microsoft Graphモジュール*1をPowerShellにインストールしておきます。

アクセスレビューの設定内容

今回は以下の設定値でアクセスレビューを作成します。

設定項目 パラメータ名 設定内容 備考
アクセスレビュー名 displayName "チームの所属ユーザーアクセスレビュー" -
説明 descriptionForAdmins "チームの所属ユーザーを棚卸します" -
レビュー担当者のメールの追加コンテンツ descriptionForReviewers "チームの所属ユーザーを棚卸をお願いします" レビュアーに届くアクセスレビュー通知メール内の本文
アクセスレビュー対象ユーザー accessReviewQueryScope チームに所属するユーザー全員（所有者・メンバー・ゲストユーザー） -
レビュアー reviewers 該当チームの所有者 -
レビュー終了時の通知先 accessReviewNotificationRecipientQueryScope 管理者 -
リソースへの結果の自動適用 autoApplyDecisionsEnabled 有効(true) レビュー期間終了後、レビュー結果を自動適用するかどうか
レビュー担当者が応答しない場合、既定の結果を適用する defaultDecisionEnabled 有効(true) レビューが終了日まで放置された場合、指定のレビュー結果を自動適用するかどうか
※適用する結果は以下「既定の結果」で指定
既定の結果 defaultDecision "Deny" レビューが終了日まで放置された場合の自動適用結果
※チームから削除する場合はDenyを指定
メール通知 mailNotificationsEnabled 有効(true) -
リマインダー reminderNotificationsEnabled 有効(true) -
正当な理由が必要 justificationRequiredOnApproval 無効(false) レビュー時に入力する「理由」欄を必須とするかどうか
レビュー期間 instanceDurationInDays 1週間 日数で指定する
※1週間の場合は"7"と指定する
頻度 recurrence
\pattern
\interval・interval		 毎月 毎月の場合、typeに"absoluteMonthly"を指定、intervalに"1"を指定する
※例えば三か月ごとであればintervalは"3"になる
レビュー開始日 recurrence
\range
\startDate		 "2024-05-01" yyyy-MM-dd形式で指定する
回数 recurrence
\range
\type		 設定しない（無期限で実施する） 終了日を設けない場合はtypeに"noEnd"を指定する

アクセスレビュー作成コマンド

まず、MgGraphへ接続します。

パラメータのScopesにはアクセスレビューを参照・上書きできる権限（AccessReview.ReadWrite.All）を指定し、TenantIDへ接続するテナントのIDを指定します。

※テナントIDはMicrosoft Entra管理センターの[概要]画面より確認できます

Connect-MgGraph -Scopes "AccessReview.ReadWrite.All" -TenantId "テナントID"

アクセスレビュー作成にはNew-MgIdentityGovernanceAccessReviewDefinition*2コマンドを利用します。

$paramsの中へアクセスレビューの各種設定値を格納し、最後に$paramsをパラメータにしてNew-MgIdentityGovernanceAccessReviewDefinitionを実行する流れとなります。

★部分のパラメータについては、実際の値へ書き換えて実行してください。（アクセスレビュー対象ユーザー、レビュアー、レビュー終了時の通知先の3箇所）

$params = @{
    displayName = "チームの所属ユーザーアクセスレビュー" #アクセスレビュー名
    descriptionForAdmins = "チームの所属ユーザーを棚卸します" #説明
    descriptionForReviewers = "チームの所属ユーザーを棚卸をお願いします" #レビュー担当者のメールの追加コンテンツ
    scope = @{
        "@odata.type" = "#microsoft.graph.accessReviewQueryScope"
        query = "/groups/★レビュー対象チームのグループID/transitiveMembers"  #アクセスレビュー対象ユーザー
        queryType = "MicrosoftGraph"
    }
    reviewers = @(
        @{
            query = "/groups/★レビュー対象チームのグループID/owners" #レビュアー
            queryType = "MicrosoftGraph"
        }
    )
    additionalNotificationRecipients = @(
    @{
    notificationTemplateType = "CompletedAdditionalRecipients"
    notificationRecipientScope = @{
        "@odata.type" = "#microsoft.graph.accessReviewNotificationRecipientQueryScope"
        query = "/v1.0/users/★レビュー終了時に通知するユーザーのオブジェクトID"  #レビュー終了時の通知先
        queryType = "MicrosoftGraph"
    }
   }
   )
    settings = @{
        autoApplyDecisionsEnabled = $true  #リソースへの結果の自動適用
        defaultDecisionEnabled = $true  #レビュー担当者が応答しない場合、既定の結果を適用する
        defaultDecision = "Deny"  #既定の結果
        mailNotificationsEnabled = $true  #メール通知
        reminderNotificationsEnabled = $true  #リマインダー
        justificationRequiredOnApproval = $false  #正当な理由が必要
        instanceDurationInDays = 7  #レビュー期間
        recurrence = @{
            pattern = @{
                type = "absoluteMonthly" #レビューの間隔（年ごと／月ごと）
                interval = 1  #レビューの間隔
                dayOfMonth = 0
            }
            range = @{
                type = "noEnd"  #レビューの繰り返し種類（無期限の場合はnoEndを指定する）
                startDate = "2024-05-01"  #レビュー開始日
            }
        }
    }
}
#アクセスレビュー実行
New-MgIdentityGovernanceAccessReviewDefinition -BodyParameter $params

コマンドを実行すると、戻りとしてアクセスレビューのID、作成日時、アクセスレビューの説明、レビュー担当者のメールの追加コンテンツが出力されます。

アクセスレビュー作成コマンド実行結果画面

今回ご紹介したもの以外にも、アクセスレビュー作成時に指定できるパラメータはいくつもあります。

MicrosoftのドキュメントにいくつかExmpleが掲載されていますので*3、こちらも参考にしてみてください。

アクセスレビュー取得・削除コマンド

作成と合わせて、アクセスレビューの取得、削除コマンドについても紹介します。

アクセスレビューの取得

取得はGet-MgIdentityGovernanceAccessReviewDefinitionコマンド*4を利用します。

取得件数のオプションを付けないと出力される結果が一部のみになるため、-Topや-Allオプションを指定してください。

※既定の出力件数が何件であるかはドキュメントに記載なし

Get-MgIdentityGovernanceAccessReviewDefinition -All

特定のアクセスレビューのみ取得したい場合は、アクセスレビューIDでフィルタできます。

Get-MgIdentityGovernanceAccessReviewDefinition -AccessReviewScheduleDefinitionId アクセスレビューのID

なお、パラメータに指定するアクセスレビューのIDは、GUI上であれば以下より確認できます。

Entra管理センター＞アクセスレビュー＞各アクセスレビューの詳細画面

Get-MgIdentityGovernanceAccessReviewDefinitionを実行した際に取得できる項目は以下の通りです。

ID アクセスレビューのID
CreateDateTime アクセスレビュー作成日時（UTCで出力されます）
DescriptionForAdmin アクセスレビューの説明
DescriptionForReviewers レビュー担当者のメールの追加コンテンツ
アクセスレビュー取得コマンド実行結果画面

Get-MgIdentityGovernanceAccessReviewDefinitionコマンドで取得できるすべての項目を出力したい場合は、以下コマンドで全項目出力できます。

Get-MgIdentityGovernanceAccessReviewDefinition -AccessReviewScheduleDefinitionId アクセスレビューのID | Select-Object *

また、Get-MgIdentityGovernanceAccessReviewDefinitionコマンドではレビューの開始日・終了日は取得できませんので、開始日・終了日も取得したい場合はGet-MgIdentityGovernanceAccessReviewDefinitionInstanceコマンド*5を利用してください。

アクセスレビューの削除

削除は、Remove-MgBetaIdentityGovernanceAccessReviewDefinitionコマンド*6を利用します。

アクセスレビューのIDをパラメータにしコマンド実行します。

Remove-MgBetaIdentityGovernanceAccessReviewDefinition -AccessReviewScheduleDefinitionId アクセスレビューのID
アクセスレビュー削除コマンド実行結果画面

終わりに

アクセスレビューはまだ発展途上の機能であるためか、GUI上からは操作・管理しきれない部分が多々あります。

例えば、アクセスレビューが全部で何件あるかは画面上からは確認できないですし、検索機能も最低限です。また、アクセスレビューの一覧出力やCSVインポートにより一括作成するなどの機能は標準では備わっていません。

これら、PowerShellコマンドでのやり方を知って、ぜひアクセスレビューの管理にお役立てください。

*1:https://learn.microsoft.com/ja-jp/powershell/microsoftgraph/installation?view=graph-powershell-1.0

*2:https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.governance/new-mgidentitygovernanceaccessreviewdefinition?view=graph-powershell-1.0

*3:https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.governance/new-mgidentitygovernanceaccessreviewdefinition?view=graph-powershell-1.0#examples

*4:https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.governance/get-mgidentitygovernanceaccessreviewdefinition?view=graph-powershell-1.0

*5:https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.identity.governance/get-mgidentitygovernanceaccessreviewdefinitioninstance?view=graph-powershell-1.0

*6:https://learn.microsoft.com/en-us/powershell/module/microsoft.graph.beta.identity.governance/remove-mgbetaidentitygovernanceaccessreviewdefinition?view=graph-powershell-beta

執筆担当者プロフィール
Hiroko, Kimura

Hiroko, Kimura（日本ビジネスシステムズ株式会社）

Microsoft 365製品の提案～運用が担当領域、特にTeams／Teams Phone多めです。趣味は音楽とテレビと映画。趣味にしたいのは筋トレ（エンジニアには筋肉が必要）。

担当記事一覧