PowerShellでAzure ADの情報を収集

皆さんこんにちは。国井です。

最近、「Windows Server Active DirectoryからAzure Active Directoryに移行したいのですが」というご相談を伺うようになってきました。
Azure Active DirectoryをWindows Server Active Directory的な感じで使いたいと考えた場合、ひとつの課題として出てくるのがPowerShellでADを扱いたいというテーマだと思います。
もちろん、Azure Active Directory (Azure AD)にはPowerShellツールが用意されているけれど、コマンドレットで用意されていないようなことにチャレンジしたいとなると、APIレベルでのアクセスが必要となります。
Azure ADではGraph APIを利用することでAPIレベルでのAzure ADへのアクセスができますが、インフラ屋の私としてはできればVisual Studioを使わないで実現したい。
そんなときに覚えておきたいのが、PowerShellを使ってGraph APIを扱う方法です。
では、順番に見てみましょう。

■ADALライブラリのロード

PowerShellからGraph APIを扱う場合、ADAL(Active Directory Authentication Library)を活用します(ADALそのものの説明は別の機会に)。ADALのライブラリ(ADALのLはライブラリのLじゃない?という突っ込みはしないでね)はいくつかの方法で入手できますが、一番手っ取り早いのはAzure PowerShellをインストールする方法です。Azure PowerShell をインストールすると、C:\Program Files (x86)\Microsoft SDKs\Azure\PowerShell\ServiceManagement\Azure\Servicesフォルダーにライブラリファイルが生成されます。この中からMicrosoft.IdentityModel.Clients.ActiveDirectory.dllファイルを使います。ですので、Azure PowerShellをインストールしたら、該当するフォルダーにファイルがあることを確認しておいてください。

※2020年2月1日追記
上記のライブラリ入手方法は利用できなくなっているので、
代わりに nuget.exe を利用して取得してください。

■Graph APIアクセスを受けるためのAzure AD アプリの作成

クライアントからGraph APIでAzure ADにアクセスする場合、アクセスを受け付けるためのアプリをAzure AD側に追加する必要があります。このアプリはAzure管理ポータルから管理対象となるAzure ADドメインにアクセスし、[アプリケーション]から[追加]をクリックし、アプリケーションを追加します。

image

追加時に[組織で開発中のアプリケーションを追加]を選択すると、ウィザードが始まり、 [アプリケーション情報の指定]で適当な名前を入力します。

image

[アプリケーションのプロパティ]で、サインオンURLにhttp://localhostと入力し、アプリケーションID/URIには適当なURLを入れておきます。 URIは単なる識別子なので、一意でありさえすれば、実在する必要はありません。 (ここではhttp://dc.example.com)としておきます。

image

アプリケーションが出来上がったら、構成タブをクリックします。 (下の画面ではロゴを変えてしまってます)

image

画面をスクロールしたら、まずクライアントIDが表示されるので、控えておいてください。それから[キー]は通信をするうえで必要になるものなので、作成しておいてください。 (下の画面は作成後のものですが、作成前には作成ボタンがありますので、そちらを使います)

image

それから上の画面で、[他のアプリケーションに対するアクセス許可]では、Graph API経由でのアクセスを許可する範囲を定義します。以下のように設定しておけば、Azure ADのユーザー情報は少なくとも引っ張ってくることができます。(それ以上の操作が必要なときは追加でアクセス許可を与えてください) image

image

ここまでできたら、保存してAzure AD側の設定を完了します。

■PowerShellスクリプトの作成と実行

スクリプトでは、ADALのロード、アクセスするテナントの指定、AuthenticationContextオブジェクトの作成、そして行いたい操作の順に記述していきます。ここでは、Azure AD の監査レポート(auditEvents)を列挙する操作を行っています。
ちなみに下敷きにしたスクリプトはブチザッキさんの「Azure Management REST API用のBearerトークン」です。

#ADALのロード
$adal = “${env:ProgramFiles(x86)}\Microsoft SDKs\Azure\PowerShell\ServiceManagement\Azure\Services\Microsoft.IdentityModel.Clients.ActiveDirectory.dll”
$adalforms = “${env:ProgramFiles(x86)}\Microsoft SDKs\Azure\PowerShell\ServiceManagement\Azure\Services\Microsoft.IdentityModel.Clients.ActiveDirectory.WindowsForms.dll”
[System.Reflection.Assembly]::LoadFrom($adal)
[System.Reflection.Assembly]::LoadFrom($adalforms)

#アクセスするテナントの指定
$resource = “https://graph.windows.net
$clientId = “<クライアントID>
$clientSecret = “<キー>
$serviceRootURL = “https://graph.windows.net/<テナント名>.onmicrosoft.com”
$authString = “https://login.windows.net/<テナント名>.onmicrosoft.com”

#オブジェクトの作成とトークンの取得
$authContext = New-Object “Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext” -ArgumentList $authString
$clientCredential = New-Object -TypeName “Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential”($clientID, $clientSecret)
$authenticationResult = $AuthContext.AcquireToken($resource, $clientCredential)
$authHeader = $authenticationResult.CreateAuthorizationHeader()

#Azure ADから監査レポート一覧を取得
Invoke-RestMethod -Uri “$serviceRootURL/reports/auditEvents?api-version=beta” -Headers @{Authorization=$authHeader} -ContentType “application/json” | select -ExpandProperty value

以上の流れを覚えておけば、最終行の太字の部分だけ別の操作を書くことで様々な情報をAzure ADから取得できます。また、最終行の太字で書いた部分を reports/auditEvents?api-version=beta&$filter= と書けば条件設定も可能です。
例えば、1日前以降(24時間以内)のログだけ表示させたければ、最後の行を次のように書き換えます。

$1dayago = “{0:s}” -f (get-date).AddDays(-1) + “Z”
Invoke-RestMethod -Uri “$serviceRootURL/reports/auditEvents?api-version=beta&$filter=&$filter=eventTime gt $1dayago” -Headers @{Authorization=$authHeader} -ContentType “application/json” | select -ExpandProperty value

どんなことを書けば、何が取得できるかについては機会を改めて紹介できればと思いますが、少なくともこの流れを覚えておくと、何かと役に立つのではないでしょうか。

■参考情報

条件設定に利用可能なプロパティ(属性)一覧
https://graph.windows.net/<Azure ADテナント名>.onmicrosoft.com/$metadata

Using the Azure AD Graph Reporting API from PowerShell – Good Workaround! レポート結果から不適切なログが生成されている場合には管理者にメールを送信するまでの流れを紹介しているので便利
https://goodworkaround.com/2015/07/08/using-the-azure-ad-graph-reporting-api-from-powershell/

Azure Active Directory Reporting API の概要 – このブログを書いた後で気が付いたのだけど、同じようなことを紹介してくれています。
https://azure.microsoft.com/ja-jp/documentation/articles/active-directory-reporting-api-getting-started/