BoxのEventAPIのレスポンスを特定ユーザでフィルタしたい
BoxのAdventカレンダー5日目を担当します。だーはら（@daharatech）です。
BoxのEventAPIについて取り上げたいと思います。
要約
１．EventAPIをadmin_logsで叩くと全ユーザ分のログが返却される
２．インシデントやアノマリーの調査にあたって、特定ユーザのみのログが欲しいケースがあるが、BoxのEventAPIには特定のユーザを絞り込むフィルタのパラメータが存在しない
３．as-userヘッダーを使ってAPIを実行するユーザを変更し、該当ユーザのみのログを返却させればOK
どうしてフィルタリング？
Boxの管理者をしていると時折、こういった質問をユーザから受けることはありませんか？
昨日まであったファイルが見当たらない！誰が操作していたのか調べてほしい。
退職するユーザがBoxからデータを持ち出していないか調べることはできないか？
他にも、BoxShiled等を利用しているテナントでは、Box Shieldで示唆されたイベントに対して、特定ユーザのイベントを取得して調査する必要が生じるケースもあるでしょう。
もし、手動でBoxのレポートを出力したもので事足りるようでしたら問題ありません。なぜならBoxのレポートは2021年7月から特定のユーザに絞ったレポートを出力可能になっているからです。
他方、他のサーバに特定のユーザに絞ったログを送付したり、他のアプリケーションに特定ユーザのログを表示したりしたい時は、BoxのEvent APIを利用する必要があります。
BoxのEventAPIとは？
BoxはAPIを利用してユーザの操作ログを取得することができます。操作ログとは「ログイン」や「ダウンロード」「ファイル削除」等のユーザが行うアクションを記録したものです。
EventAPIによるログは最大1年前まで遡ることが可能です。
ちなみに、管理者アカウントが管理者コンソールからレポート出力をすることで操作ログ等を出力することも可能で、こちらは最大7年間保管されています。
Box EventAPIの詳細はコチラ。
https://ja.developer.box.com/reference/get-events/
Event APIを特定ユーザに絞って出力するパラメータは？
指定したユーザーまたは会社全体の過去のイベントを最大1年間遡って返します。
との記載がEventAPIのリファレンスありますので、きっとユーザを指定するパラメータが…
ユーザを指定するパラメータが…ない！！！
stream_typeというパラメータのユーザに関するオプションは「all」と「admin_logs」しかありません。
all：APIを認証したユーザのイベント（操作ログ）を出力するオプション
admin_logs：いまログインしているBoxすべてのイベント（操作ログ）を出力するオプション ※プライマリ管理者あるいは共同管理者の権限が必要です
つまり「自分のログ」か「会社全体のログ」しかオプションで選ぶことができません。困った。
Event APIを特定ユーザに絞って出力するには？
実はガイドのユーザイベントの取得ページに特定ユーザのイベントを出力させる方法が書かれています。
別のユーザーのイベントフィードを取得するには、as-userヘッダーか、そのユーザーの実際のアクセストークンを使用します。
なるほど。自分のログしか返却されないなら、「ログを取得したい人」としてAPIを叩けばよいということですね。
as-userヘッダーって何？
as-userヘッダーについて補足しておきたいと思います。
APIを実行しているユーザとは別のユーザとしてAPIを実行する際に、APIのHTTPリクエストヘッダーに付与するas-userパラメータのことをas-userヘッダーと呼びます。
as-userヘッダーについて詳しくはコチラ。
以下はBox社提供のガイドから引用したas-userヘッダーを利用する際のリクエスト方法です。LinuxやMacであればこの通りに実行するだけで[USER_ID]で指定された人としてAPIを実行できます。
[USER_ID]を調べる方法はコチラを参照してください。リンク先のfilter_termパラメータ等を利用して該当ユーザの[USER_ID]を特定してください。
curl https://api.box.com/2.0/folders/0 \
-H "as-user: [USER_ID]"
-H "authorization: Bearer [ACCESS_TOKEN]"Windows環境でPowerShellを利用してAPIを叩く場合、以下のような方法でas-userヘッダーを付与することができます。
$uri = 'https://api.box.com/2.0/folders/0'
$header = @{'Authorization'='Bearer [ACCESS_TOKEN]'; 'as-user'=[USER_ID]}
Invoke-RestMethod -Uri $uri -Method Get -Headers $header -ContentType 'application/json'このas-userですが、単に叩けばよいというものではなく、Boxアプリ側でas-userとして実行可能とするか設定しておく必要があります。設定箇所はBoxアプリの「構成」タブを開いて「高度な設定」にあります。「as-userヘッダーを使用してAPI呼び出しを行う」にチェックを付けることで、as-userヘッダーを利用したAPIアクセスができるようになります。
★ 注意 ★
as-userヘッダーは本件のようなケースにおいて非常に有効ですが、言い換えれば誰にでも成り代わってAPIが実行できてしまう危うさも持ち合わせています。そのため、as-userヘッダーの使用を有効化できるのは、以下の条件を満たす場合のみに限られます。
１．JWTによるアプリ認証であること
２．「管理者」「共同管理者」「サービスアカウント」による認証ユーザによってAPIが実行されること
３．「共同管理者」によるAPI実行を行う場合、as-userヘッダーを利用するにはアプリケーションスコープの「ユーザーを管理する」も有効化する必要がある
（３は英語版のガイドには記載があるのに、日本語版のガイドには記載がない…）
ざっくりまとめると「管理者が認めない限りas-userでAPI叩くことは許さん」ということです。
APIを叩く具体的な方法は？
Powershellを利用してas-userを利用したEventAPIの叩く一連の流れを記載します。
１．まずはユーザのIDを特定します。
例としてメールアドレスに「dahara」の文字列が存在するユーザのIDを取得してみましょう。
$token = "abcd..."
$header = @{"Authorization"="Bearer $token"}
$request = "https://api.box.com/2.0/users?filter_term=dahara"
$result = Invoke-RestMethod -Uri $request -Method Get -Headers $header -ContentType "application/json"
Write-Host $result.entries
type : user
id : 123456789
name : dahara
login : dahara.hrd@hogehoge.com
created_at : 2018-10-24T10:40:19-07:00
modified_at : 2021-11-29T04:40:00-08:00
language : ja
timezone : Asia/Tokyo
space_amount : 107374182400
space_used : 574223760
max_upload_size : 2147483648
status : active
job_title : none
phone :
address :
avatar_url : https://app.box.com/api/avatar/large/123456789
notification_email : {}id : 123456789がユーザのIDですね。もし複数のユーザがヒットした場合、返却されるjsonのentriesに複数個の結果が配列として入ります。
２．ユーザIDを利用してas-userヘッダーを用意します。
$header = @{"Authorization"="Bearer $token"; "as-user"="123456789"}３．EventAPIを叩きます。
$base_url = "https://api.box.com/2.0/events"
$request = $base_url + "?limit=500&stream_type=all"
$events = Invoke-RestMethod -Uri $request -Method Get -Headers $header -ContentType "application/json"
Write-Host $events.entries
type : event
event_id : 761db30a187be2cf0f3978ce4326fe3417117aa3
created_by : @{type=user; id=123456789; name=dahara; login=dahara.hrd@hogehoge.com}
created_at : 2021-11-27T06:01:34-08:00
recorded_at : 2021-11-27T06:01:35-08:00
event_type : ITEM_PREVIEW
session_id : w3z03mgwu2280bh9
source : @{type=file; id=715042035050; file_version=; sequence_id=0; etag=0; sha1=296bb6e85a81bd54c10
543af3e801caae3bc9b26; name=テスト.pdf; description=; size=206300; path_collection=; created_at
=2020-09-03T03:16:31-07:00; modified_at=2020-09-03T03:16:31-07:00; trashed_at=; purged_at=;
content_created_at=2020-09-03T03:13:01-07:00; content_modified_at=2020-09-03T03:13:01-07:00;
created_by=; modified_by=; owned_by=; shared_link=; parent=; item_status=active; synced=Fal
se}
type : event
event_id : 772b7ac819d2c32f3cf05aabcf90f171a1995b8f
created_by : @{type=user; id=123456789; name=dahara; login=dahara.hrd@hogehoge.com}
created_at : 2021-11-27T06:02:00-08:00
recorded_at : 2021-11-27T06:02:00-08:00
event_type : ITEM_CREATE
session_id :
source : @{type=folder; id=151028323260; sequence_id=0; etag=0; name=testfolder; created_at=2021-11-2
7T06:01:59-08:00; modified_at=2021-11-27T06:01:59-08:00; description=; size=0; path_collecti
on=; created_by=; modified_by=; trashed_at=; purged_at=; content_created_at=2021-11-27T06:01
:59-08:00; content_modified_at=2021-11-27T06:01:59-08:00; owned_by=; shared_link=; folder_up
load_email=; parent=; item_status=active; synced=False}これで指定したユーザの操作ログのみ出力することができました。
結論
特定のユーザの操作ログが欲しいときはas-userヘッダーを使ってEventAPIを叩こう！
以上。
ついでの宣伝
admin logs streaming
今回はEventAPIを叩きました。実は先日
admin_logs_streamingという新しいEventAPIが公開されました。これらは「別のAPI」として提供されるので、今回叩いたEventAPIが拡張されたり、変更されたりするわけではありません。
Box Japan Cloud Connections
Boxの日本ユーザコミュニティです。私がリーダーを務めています。
コミュニティに参加するとコミュニティSlackに参加でき、いろいろなBoxerたちと横のつながりを持つことができます。ご興味あれば参加してみてください。
この記事が気に入ったらサポートをしてみませんか？