見出し画像

Google WorkspaceをAPIで操作する——サービスアカウントの設定手順

mutta

ご注意
個人の調査・見解にもとづくため、正確性は保証できません。また、記載時点の仕様をもとにしているため、現在の画面や動作と異なる場合があります。あくまで参考情報としてご覧ください。

Google Workspace の管理者として管理コンソールで行っている操作を、プログラムから自動で実行する——それが「APIで操作する」ということです。APIはプログラムがサービスを呼び出すための窓口で、「ユーザー一覧をください」「このアカウントを停止してください」といった命令をHTTPリクエストとして送ると、Google Workspaceが応答します。ユーザーの棚卸しや退社処理の自動化など、手作業でやっていた作業がスクリプト1本で完結するようになります。
そう思ってAPIのドキュメントを開くと、最初にいくつかの概念の壁にぶつかります。
「Google CloudとGoogle Workspaceって何が違うの？」「サービスアカウントとOAuthはどちらを使えばいい？」「ドメイン全体の委任ってなに？」
これらは実際に動かしてみてはじめて関係がわかることが多く、ドキュメントを読んでいるだけだとピンとこないポイントです。この記事では、実装に入る前に理解しておきたい3つのことを整理します。

Google CloudとGoogle Workspaceは「別の管理体系」

まず混乱しやすいのがここです。
Google CloudとGoogle Workspaceは同じGoogleのサービスですが、管理の仕組みは分かれています。

Google WorkspaceのAPIを使うとき、この2つの管理体系それぞれで設定が必要です。Google Cloud Consoleだけ設定しても動きません。Google Workspace Admin Consoleだけ設定しても動きません。
ここを理解していないと「APIは有効化したのに動かない」という状況でどこを見ればいいかわからなくなります。

認証方式を選ぶ：サービスアカウントとOAuthクライアント

Google Workspaceの自動化を始めようとすると、最初に必ずぶつかるのがこの選択です。ここを間違えると設定をやり直すだけでなく、セキュリティ上のリスクにもつながります。
APIの認証には大きく2種類あります。用途が違うので最初に選んでおく必要があります。

サービスアカウント

ユーザーの操作なしにバックグラウンドで動きます。ドメイン全体の委任という仕組みを使って、管理者権限で全ユーザーのデータにアクセスできます。

サービスアカウント → (権限借用) → admin@yourdomain.com → 全ユーザーのデータ

admin@yourdomain.com の部分には、Google Workspaceドメイン内に実在するアカウントのメールアドレスを指定します。なりすまし先のアカウントが持つ権限の範囲内でAPIを呼び出せるため、操作に必要な権限を持つアカウントを指定する必要があります。
参考：Delegating domain-wide authority to a service account

  • 向いているケース：定期バッチ、ユーザー棚卸し、ライセンス管理など、管理者が全員分のデータを自動処理するとき

  • 注意点：全ユーザーのデータにアクセスできる強力な認証情報なので、キーの管理が最重要

OAuthクライアント

ユーザーがブラウザでGoogleアカウントにログインして認可するフローです。アクセスできるのはログインしたユーザー自身のデータのみ。

ユーザーがログイン → そのユーザーのデータのみアクセス可

  • 向いているケース：ユーザー向けWebアプリ、ユーザー自身のDriveやCalendarを扱うツール

  • 利点：権限の範囲が限定されるのでセキュリティリスクが低い

選び方の原則：「誰かが代わりに全員分のデータを処理する」ならサービスアカウント、「ユーザーが自分のデータを操作する」ならOAuthクライアントです。

サービスアカウントの設定手順

ここからはサービスアカウントを使った設定手順です。OAuthクライアントについては別の記事で説明します。設定が必要な場所は3つの層に分かれています。

層①  API有効化（GCP）
      → ここで「このAPIを使っていいよ」という許可
層②  Domain-wide Delegation有効化（GCP）
      → ここで「管理者権限を借用できるよ」という設定
層③  OAuthスコープの承認（GWS Admin Console）
      → ここで「どのデータにアクセスしていいか」の範囲

この3つがすべて揃ってはじめて動きます。よくあるエラーとその原因はこうです。

エラーが出たらこの3層のどこが抜けているかを確認するのが最初のステップです。
なお、以降ではユーザー管理API（Admin SDK API）を例として説明しますが、3層の構造はサービスアカウントを使う場合はAPIの種類を問わず共通です。

層① APIを有効化する（Google Cloud Console）

Google Cloud Console > APIとサービス > ライブラリ を開き、必要なAPIを検索して選択し、「有効にする」をクリックします。ユーザー管理を例にとると、最低限この2つが必要です。他のAPIを使う場合は、対応するAPIをここで有効化します。

有効化後、反映に数分かかることがあります。

層② サービスアカウントの設定（Google Cloud Console）

Google Cloud Console > IAMと管理 > サービスアカウント を開き、「サービスアカウントを作成」をクリックします。
作成フローは3ステップありますが、入力が必要なのは最初の①だけです。

① サービスアカウントの作成

  • サービスアカウント名：用途がわかる名前（例：gws-user-management）

  • サービスアカウントID：名前から自動生成されるので、通常はそのままでOK。<ID>@<プロジェクトID>.iam.gserviceaccount.com という形式のメールアドレスになります

  • 説明：任意。何のために作ったかを書いておくと後で迷わない

入力したら「作成して続行」をクリックします。

② 権限（省略可）／ ③ アクセス権を持つプリンシパル（省略可）

どちらもスキップして「完了」をクリックします。
作成後、サービスアカウントの一覧から対象のアカウントをクリックして詳細画面を開きます。「詳細」タブを下にスクロールすると「詳細設定」セクションに「ドメイン全体の委任」があり、クライアント ID（数字の羅列）が表示されています。この値を次のステップで使うのでコピーしておきます。
続けて「鍵」タブを開き、「キーを追加」→「新しい鍵を作成」をクリックします。キーのタイプは「JSON」（推奨）を選択し、「作成」をクリックするとJSONファイルがダウンロードされます。これがスクリプトで使う認証情報になります。
※このファイルを紛失すると復元できません。安全な場所に保管してください。

層③ OAuthスコープを承認する（Google Workspace Admin Console）

Google Workspace Admin Console > セキュリティ > アクセスとデータ管理 > APIの制御 > ドメイン全体の委任 を開き、「新しく追加」をクリックします。Google Cloud Console のサービスアカウント詳細 > 「詳細」タブ > 詳細設定 > ドメイン全体の委任 にある「Google Workspace 管理コンソールを表示」ボタンを使うと、この画面に直接遷移できます。

  • クライアント ID：Google Cloud Consoleのサービスアカウント詳細でコピーした数字の羅列を入力

  • OAuthスコープ：アクセスしたいデータの範囲をカンマ区切りで1行で入力

# 読み取りのみ（ユーザー一覧取得・ライセンス確認）
<https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/apps.licensing>

「承認」をクリックして設定完了です。

設定後の確認

3層の設定が終わったら、以下を順番にチェックします。

□ GCP > APIライブラリ > Admin SDK API が「有効」になっている
□ Google Cloud Console のサービスアカウント詳細でクライアント ID を確認済み
□ GWS Admin Console > ドメイン全体の委任 にクライアントIDが登録されている
□ 登録されているOAuthスコープに必要なものが含まれている

これで実際にAPIを呼び出す準備が整いました。

いいなと思ったら応援しよう！