Terraform を用いると、GCP 環境内にリソースを作成できます。GCP で組織を用いる際に必要となる Cloud Identity は GCP の外に存在する Google のサービスです。Cloud Identity が出力するログを GCP 内の Cloud Logging に取り込む方法について、Terraform モジュールのソースコードを確認してみます。

用語

過去の経緯により、ドキュメントでは似たような用語が使われていることがあるため注意します。

• Google Stackdriver Monitoring は GCP Cloud Monitoring の旧称です。
• Google Stackdriver Logs は GCP Cloud Logging の旧称です。
• G Suite は Google Workspace の旧称です。
• Cloud Identity は Google Workspace の機能制限版です。

Terraform GSuite Export Module

Terraform GSuite Export Module は Terraform モジュールの一つです。サンプルとして紹介されているモジュールの使い方の一つとして、「Cloud Scheduler で Cloud Functions を定期実行して Cloud Identity API を実行し、結果を Cloud Logging に書き込む」というものがあります。

Cloud Functions 内のソースコードについて

Cloud Identity API を実行する Cloud Functions のソースコードは以下のようになっています。gsuite_exporter.cli の sync_all を実行しています。

• PROJECT_ID は、Cloud Identity から取得したログを書き込む Cloud Logging が存在するプロジェクトの ID です。
• GSUITE_ADMIN_USER は、Cloud Identity における Admin ユーザです。

main.py

import base64
import json
from gsuite_exporter.cli import sync_all


def run(data, context):

    # Decode Data From Pubsub Message
    name = base64.b64decode(data['data']).decode('utf-8')

    # Load Data in JSON
    dictionary = json.loads(name)

    # Parse JSON to Set Variables
    project_id = dictionary['PROJECT_ID']
    gsuite_admin_user = dictionary['GSUITE_ADMIN_USER']

    # Run Log Sync
    sync_all(
            admin_user=gsuite_admin_user,
            api='reports_v1',
            applications=['login', 'admin', 'drive', 'mobile', 'token'],
            project_id=project_id,
            exporter_cls='stackdriver_exporter.StackdriverExporter'
        )

professional-services レポジトリについて

gsuite_exporter.cli の sync_all は professional-services レポジトリの tools 内に存在しています。

• professional-services/tools/gsuite-exporter

Cloud Identity における Admin、Drive、Logins、Mobile、OAuth Tokens という5つの Audit Activity の API を実行するクライアントを実装しています。

例えば Logins の場合、ログイン履歴を取得する API を利用しています。

GET https://www.googleapis.com/admin/reports/v1/activity/users/all/applications/login

cli.py のインストールおよび実行

gsuite_exporter.cli の sync_all を Cloud Functions で定期実行する際に何らかの不具合があった場合、手動で cli.py を実行して sync_all の動作を確認できると便利です。簡単な実行例を記載します。

pip インストールできます。

python3 -m pip install gsuite-exporter

以下のオプションがサポートされています。

python3 -m gsuite_exporter.cli --help

usage: cli.py [-h] --admin-user ADMIN_USER [--api API] --applications
              APPLICATIONS [APPLICATIONS ...] --project-id PROJECT_ID
              [--exporter EXPORTER] [--credentials-path CREDENTIALS_PATH]
              [--offset OFFSET]

optional arguments:
  -h, --help            show this help message and exit
  --admin-user ADMIN_USER
                        The GSuite Admin user email.
  --api API             The GSuite Admin API.
  --applications APPLICATIONS [APPLICATIONS ...]
                        The GSuite Admin Applications.
  --project-id PROJECT_ID
                        The project id to export GSuite data to.
  --exporter EXPORTER   The exporter class to use.
  --credentials-path CREDENTIALS_PATH
                        The service account credentials file.
  --offset OFFSET       The offset to fetch logs from before the last sync (in
                        minutes).

cli.py は内部的には google-api-python-client レポジトリを利用しています。引数として以下のものを指定することにします。

• --applications login → Logins レポートのログを取得します。
• --project-id → 出力先となる Cloud Logging のプロジェクトID です。
• --admin-user → Cloud Logging において Admin 権限を持つユーザを指定します。
• --credentials-path 以下の権限を持つサービスアカウントの鍵ファイルのパスを指定します。
  • --project-id において Cloud Logging への書き込み権限を持つ。
  • Cloud Identity における権限を --admin-user から委譲されている。
  • --project-id において OAuth トークン発行権限を持つ。

実行例

python3 -m gsuite_exporter.cli \
--applications login \
--project-id my-project-20210506-312913 \
--admin-user admin-xxx@qoosky.io \
--credentials-path ~/myproject-20210506-8db7b758496b.json 

サービスアカウントの準備

cli.py の --credentials-path で指定したパスの鍵ファイルを持つサービスアカウントを準備します。

Cloud Identity の Admin から権限を委譲したサービスアカウントで Cloud Identity の API を実行するために、二つの API を有効化しておきます。

OAuth2 トークンを発行するための API:

Workspace (Cloud Identity) API:

作成したサービスアカウントには、以下の三つの権限を付与します。

OAuth2 トークンを発行して権限を委譲してもらうための設定を有効化します。

OAuth2 Client ID が表示されます。

Cloud Identity に Admin ユーザでログインして「Security → API controls」をクリックします。

「MANAGE DOMAIN WIDE DELEGATION」をクリックします。

確認した Client ID と OAuth スコープ https://www.googleapis.com/auth/admin.reports.audit.readonly を入力します。Cloud Identity における権限委譲のドキュメントは以下を参照します。

• https://support.google.com/a/answer/162106
• https://developers.google.com/admin-sdk/reports/v1/guides/delegation

実行してみます。

[vagrant@localhost ~]$ python3 -m gsuite_exporter.cli --applications login --project-id my-project-20210506-312913 --admin-user admin-xxx@qoosky.io --credentials-path ~/my-project-20210506-312913-ada51c5c0771.json

INFO:gsuite_exporter.auth:Getting credentials from file '/home/vagrant/my-project-20210506-312913-ada51c5c0771.json' ...
INFO:gsuite_exporter.auth:Getting credentials from file '/home/vagrant/my-project-20210506-312913-ada51c5c0771.json' ...
INFO:__main__:reports_v1.login --> stackdriver_exporter.StackdriverExporter (projects/my-project-20210506-312913/logs/login) [starting new sync] from None (offset => 0 mn)
INFO:__main__:reports_v1.login --> stackdriver_exporter.StackdriverExporter (projects/my-project-20210506-312913/logs/login) [55 new records synced]

55 new records synced 55 のログが Cloud Logging に取り込まれました。

取り込み処理を行った時刻のログとして Cloud Logging に取り込まれることに注意します。

stackdriver_exporter.py#L120

            'timestamp': {'seconds': int(time.time())},

Cloud Identity におけるログの時刻は jsonPayload.report_timestamp として格納されます。

stackdriver_exporter.py#L130

            'report_timestamp': self.get_time_dict(record)

cli.py を再度実行する際には、最新のログの timestamp の値を確認して、Cloud Identity API の startTime に指定しています。ログの重複した取り込みを回避するための処理です。

cli.py#L82

        records_stream = fetcher.fetch(application=app, start_time=start_time)

補足: Cloud Identity の設定で対応する方法

本ページで扱った Terraform モジュールを使わずに、Cloud Identity の設定でログを GCP Cloud Logging にエクスポートすることができます。

「Account settings」をクリックします。

「Legal and compliance」をクリックします。

「Enabled」を選択します。

「組織」の Cloud Logging で Cloud Identity のログが確認できるようになりました。

特にログインイベントについては admin.google.com 以外の認証でもログに追記されることに注意します。例えば GCP Cloud Console へのログインであってもログに出力されます。参考: Google Workspace Login audit

参考

admin.google.com へのログインを可能にするためには、Admin Role が付与されている必要があります。

権限がないユーザは、組織のドメインを持つ場合であっても、一般の gmail.com ユーザと同様に Cloud Identity にはログインできません。

ログの遅延について

Cloud Identity のログ出力は完全にリアルタイムではないことがあります。

Terraform ライブラリを使う場合であっても、Cloud Identity の設定を用いる場合であっても、ログが遅延することを考慮する必要があります。

Log-entry delays. Google Cloud analyzes and indexes the login logs before emitting them. This can take up to a few hours. The latency allows Google Cloud to analyze the logs for some event types, such as suspicious login and attack warning logs. For details on the latency, see Data retention and lag times.
https://cloud.google.com/logging/docs/audit/troubleshooting-faq-gsuite#delayed