Help us understand the problem. What is going on with this article?

Office 365 Management API の使い方 with PowerShell

この記事の内容

本記事では、Office 365 Management API の中でも、特に Office 365 管理アクティビティ API を利用して、Office 365 のログを取得する方法をご紹介します。特に以下の手順では、Audit.Generalのサブスクリプションを作成し、そのサブスクリプションから監査ログを取得してみます。本記事ではすべてPowerShellを利用して行います。

Office 365 Management API とは?

Office 365 Management API は Office 365 の中の、サービス通信、セキュリティ、コンプライアンス、レポート作成、監査などの管理タスクに対応した、API のプラットフォームです。

特に、Office 365 管理アクティビティ API は、Office 365 と Azure Active Directory のアクティビティ ログからの、ユーザー、管理者、システム、およびポリシー アクションとポリシー イベントについての情報を提供します。

基本的な手順について

基本的な手順は、Office 365 Management API の使用を開始するを参考にしていますが、少し古い部分もあるため、下記の4つのステップとしてまとめています。

Step 1. Azure AD でアプリケーションを登録する。

アプリケーションが Office 365 Management API にアクセスできるようにするには、アプリケーションを Azure AD に登録する必要があります。これにより、アプリケーションの ID を設定して、API へのアクセスに必要なアクセス許可レベルを指定できるようになります。

Step 2. Office 365 API サブスクリプションを作成する。

各アクティビティAPIからデータを取得するには、サブスクリプションを作成する必要があります。
ここでは、Audit.Generalのサブスクリプションを作成しますが、ほかにも下記があります。
*Audit.AzureActiveDirectory
*Audit.Exchange
*Audit.SharePoint
*Audit.General (上記のコンテンツ タイプに含まれない、その他すべてのワーク ロードが含まれます)
*DLP.All (すべてのワークロードの DLP イベントのみ)

なお、アクティビティAPIのサブスクリプションの種類や詳細については、Office 365 管理アクティビティ API の操作をご参照ください。

Step 3. Azure AD からアクセス トークンを要求する。

Azure AD で設定されているアプリケーションの資格情報を使用すると、アプリケーションは、テナント管理者の追加の操作を必要とすることなく、継続的に同意済みのテナントの追加のアクセストークンを要求します。

4. Office 365 Management API の呼び出し。

アプリケーションを認証して承認するため、アプリ専用アクセス トークンが Office 365 Management API に渡されます。

同意とアクセストークンの要求のシーケンスは下記図のようになります。
image.png

Step 1. Azure AD でアプリケーションを登録する。

Azure AD でのアプリケーションの登録は Azure Portal の Azure AD のメニューで行います。
image.png

Azure AD のアプリの登録から、新規登録をクリックします。名前を記入し、あとはデフォルトの値で登録します。

その後、そのアプリケーションを選択し、APIのアクセス許可から、Office 365 Management API を選択します。
image.png

そして、アクセス許可の要求で、「委任されたアクセス許可」と「アプリケーションの許可」でそれぞれ必要なものをすべてクリックし、許可を追加します。
image.png

そしてドメインに管理者の同意を与えます。
image.png

次に、証明書とシークレットに行き、新しいクライアントシークレットをクリックします。
image.png

期限と説明を設定して作成します。作成時にシークレットが出てくるので、メモ帳などにコピーペーストしておきます。
image.png

Step 2. Office 365 API サブスクリプションを作成する。

次に Office 365 API のサブスクリプションを作成します。
まず、下記の<>を入力して、PowerShellで実行します。$Publisherは https://guidgenerator.com/ でGUIDをひとつ作って入力します。

$ClientID = "<GUID> from AAD App Registration"
$ClientSecret = "<clientSecret> from AAD App Registrtion"
$loginURL = "https://login.microsoftonline.com/"
$tenantdomain = "<domain>.onmicrosoft.com"
$TenantGUID = "<tenantguid> from AAD"
$resource = "https://manage.office.com"
$body = @{grant_type="client_credentials";resource=$resource;client_id=$ClientID;client_secret=$ClientSecret}
$oauth = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body
$headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"} 
$publisher = "<randomGuid>" Get a guid from https://guidgenerator.com/

そして、下記コマンドでAudit.Generalのサブスクリプションを作ります。(&がエスケープできない場合は、適宜変更してください。)

Invoke-WebRequest -Method Post -Headers $headerParams -Uri https://manage.office.com/api/v1.0/$tenantGuid/activity/feed/subscriptions/start?contentType=Audit.General&PublisherIdentifier=$Publisher

(参考:DLP.ALLのサブスクリプションの作成は下記のようになります。)

Invoke-WebRequest -Method Post -Headers $headerParams -Uri https://manage.office.com/api/v1.0/$tenantGuid/activity/feed/subscriptions/start?contentType=DLP.ALL&PublisherIdentifier=$Publisher

Step 3. Azure AD からアクセストークンを要求する。

下記コマンドをPowerShellで実行します。

$ClientID = "<GUID> from AAD App Registration"
$ClientSecret = "<clientSecret> from AAD App Registrtion"
$loginURL = "https://login.microsoftonline.com/"
$tenantdomain = "<domain>.onmicrosoft.com"
$TenantGUID = "<tenantguid> from AAD"
$resource = "https://manage.office.com"

# auth
$body = @{grant_type="client_credentials";resource=$resource;client_id=$ClientID;client_secret=$ClientSecret}
$oauth = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body
$headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

正しく進むと、下記のように Bearer Token を取得することができます。
image.png

Step 4. Office 365 Management API の呼び出し。

Office 365 Management API を呼び出し、ログを取得してみます。時刻は必要に合わせて変更ください(startTimeとendTimeの間が24時間以内である必要があります)。

#Time Setting
$currentUTCtime = (Get-Date).ToUniversalTime()
$endTime = $currentUTCtime(-48) | Get-Date -Format yyyy-MM-ddThh:mm:ss
$startTime = $currentUTCtime.AddHours(-72) | Get-Date -Format yyyy-MM-ddThh:mm:ss

#Subscription and Record Type Setting
$contentTypes = "Audit.General"
$recordTypes = 0

#ContentTypesを複数セットした際にループを回す
$contentTypes = $contentTypes.split(",")
    #Loop for each content Type like Audit.General
    foreach($contentType in $contentTypes){
        $listAvailableContentUri = "https://manage.office.com/api/v1.0/$tenantGUID/activity/feed/subscriptions/content?contentType=$contentType&PublisherIdentifier=$publisher&startTime=$startTime&endTime=$endTime"
        do {
            #List Available Content
            $contentResult = Invoke-RestMethod -Method GET -Headers $headerParams -Uri $listAvailableContentUri
            $contentResult.Count

            #Loop for each Content
            foreach($obj in $contentResult){
                #Retrieve Content
                $data = Invoke-RestMethod -Method GET -Headers $headerParams -Uri ($obj.contentUri)
                $data.Count                 
            }

            #Handles Pagination
            $nextPageResult = Invoke-WebRequest -Method GET -Headers $headerParams -Uri $listAvailableContentUri
            If(($nextPageResult.Headers.NextPageUrl) -ne $null){
                $nextPage = $true
                $listAvailableContentUri = $nextPageResult.Headers.NextPageUrl
            }
            Else{$nextPage = $false}
        } until ($nextPage -eq $false)
    }

上手くデータが取得できれば、下記のようにデータが取得できます。
image.png

まとめ

簡単ではありましたが、Office 365 の Management API を利用して、特に 管理アクティビティ API から Audit.General のログを取得してみました。

*本稿は、個人の見解に基づいた内容であり、所属する会社の公式見解ではありません。また、いかなる保証を与えるものでもありません。正式な情報は、各製品の販売元にご確認ください。

YoshiakiOi
日本マイクロソフト株式会社 Azure & Security プリセールスエンジニア。 記事は個人の見解に基づいた内容であり、所属する会社の公式見解ではありません。また、記事中の情報はいかなる保証を与えるものでもありません。正式な情報は、各製品の販売元にご確認ください。
microsoft
マイクロソフトのメンバーが最新の技術情報をお届けします。Twitterアカウント(@msdevjp)やYouTubeチャンネル「クラウドデベロッパーちゃんねる」も運用中です。
https://aka.ms/MSFT-Docs-JPN
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした