Chat アプリと Google Chat API リクエストの認証と認可

認証と認可は、それぞれ ID の検証とリソースへのアクセスに使用されるメカニズムです。このドキュメントでは、Chat アプリと Chat API リクエストの認証と認可の仕組みについて概説します。

プロセスの概要

次の図は、Google Chat の認証と認可の大まかな手順を示しています。

Google Chat の認証と認可の概要
図 1. Google Chat の認証と認可の手順の概要。

  1. Google Cloud プロジェクトを構成し、Chat API を有効にして、Chat アプリを構成する: 開発中に、Google Cloud プロジェクトを作成します。Google Cloud プロジェクトで、Chat API を有効にし、Chat アプリを構成して、認証を設定します。詳しくは、Google Workspace で開発するとChat アプリを作成するをご覧ください。

  2. Chat API を呼び出す: アプリが Chat API を呼び出すと、認証情報は Chat API に送信されます。アプリがサービス アカウントで認証する場合、認証情報はアプリのコードとともに送信されます。アプリで、まだ付与されていないユーザーの認証を使用して Chat API を呼び出す必要がある場合は、ログインを促すメッセージがユーザーに表示されます。

  3. リソースをリクエストする: アプリが、認証の設定時に指定したスコープでのアクセスを要求します。

  4. 同意を求める: アプリがユーザーとして認証されている場合、OAuth 同意画面が表示されます。これにより、ユーザーはリクエストされたデータへのアクセスをアプリに許可するかどうかを決定できます。サービス アカウントによる認証には、ユーザーの同意は必要ありません。

  5. リソースの承認済みリクエストを送信する: ユーザーが認可スコープに同意すると、アプリは認証情報とユーザーが承認したスコープをリクエストにバンドルします。アクセス トークンを取得するために、リクエストが Google の承認サーバーに送信されます。

  6. Google がアクセス トークンを返します。アクセス トークンには、付与されたスコープのリストが含まれています。返されたスコープのリストがリクエストされたスコープよりも制限が厳しい場合、アプリはトークンによって制限されたすべての機能をオフにします。

  7. リクエストされたリソースにアクセスする: アプリは Google のアクセス トークンを使用して Chat API を呼び出し、Chat API リソースにアクセスします。

  8. 更新トークンを取得する（省略可）: アプリが 1 つのアクセス トークンの有効期間を超えて Google Chat API にアクセスする必要がある場合は、更新トークンを取得できます。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。

  9. リソースの追加をリクエストする: アプリに追加のアクセス権が必要な場合は、新しいスコープを付与するようユーザーに求めるメッセージが表示され、アクセス トークンを取得するための新しいリクエストが行われます（手順 3～6）。

チャットアプリで認証が必要な場合

チャットアプリは、ユーザー操作に応じて、または非同期でメッセージを送信できます。また、Chat スペースの作成や Chat スペース内のユーザーのリストの取得などのタスクを、ユーザーに代わって完了することもできます。

Chat アプリがレスポンスの処理中に Chat API または別の Google API を呼び出す場合を除き、ユーザー操作に応答するために認証は必要ありません。

ユーザーの代わりに非同期メッセージを送信したりタスクを実行したりするには、Chat アプリが Chat API に RESTful リクエストを発行します。この API には認証と認可が必要です。

ユーザー操作に対するレスポンスで認証が不要

Google Chat アプリは、インタラクション イベントを受信して同期的に応答するために、ユーザーまたは Chat アプリとして認証する必要はありません。

Google Chat アプリは、ユーザーが Chat アプリを操作または起動するたびに、次のようなインタラクション イベントを受信します。

  • ユーザーが Chat アプリにメッセージを送信します。
  • ユーザーが Chat 用アプリに @メンションしました。
  • ユーザーが Chat アプリのスラッシュ コマンドのいずれかを呼び出します。

次の図は、Chat ユーザーと Chat アプリ間のリクエスト / レスポンスのシーケンスを示しています。

Chat 用アプリの操作イベントに認可は不要
図 2. Chat アプリのインタラクション イベントでは認証は必要ありません。

  1. ユーザーが Google Chat の Chat アプリにメッセージを送信します。
  2. Google Chat からアプリにメッセージが転送されます。
  3. アプリはメッセージを受信して処理し、Google Chat にレスポンスを返します。
  4. Google Chat によって、ユーザーまたはスペース内に回答が表示されます。

このシーケンスは、Chat アプリのインタラクション イベントごとに繰り返されます。

非同期メッセージには認証が必要

非同期メッセージは、Chat アプリが Chat API にリクエストを送信するときに発生します。このリクエストには認証と承認が必要です。

Chat API を呼び出すと、Chat アプリは Google Chat にメッセージを投稿したり、タスクを完了したり、ユーザーに代わってデータにアクセスしたりできます。たとえば、サーバーの停止を検出すると、Chat アプリは Chat API を呼び出して次のことができます。

  • サービス停止の調査と修正専用の Chat スペースを作成します。
  • Chat スペースにユーザーを追加する。
  • Chat スペースにメッセージを投稿して、サービス停止の詳細を伝えます。

次の図は、Chat アプリと Chat スペース間の非同期メッセージ シーケンスを示しています。

非同期メッセージで認証が必要
図 3. 非同期メッセージには認証が必要です。

  1. Chat アプリは、spaces.messages.create メソッドを使用して Chat API を呼び出してメッセージを作成し、HTTP リクエストにユーザー認証情報を含めます。
  2. Google Chat は、サービス アカウントまたはユーザーの認証情報を使用して Chat アプリを認証します。
  3. Google Chat は、指定された Chat スペースにアプリのメッセージをレンダリングします。

Chat API のスコープ

OAuth 同意画面を設定し、スコープを選択することで、ユーザーとアプリの審査担当者に表示する情報を定義し、後でアプリを公開できるようにアプリを登録します。

アプリに付与されるアクセスレベルを定義するには、認可スコープを特定して宣言する必要があります。認可スコープは、Google Workspace アプリの名前、アクセスするデータの種類、アクセスレベルを含む OAuth 2.0 URI 文字列です。

非機密のスコープ

スコープコード 説明
https://www.googleapis.com/auth/chat.bot

Chat アプリがチャットを表示し、メッセージを送信できるようにします。

このスコープは、サービス アカウントによるアプリ認証のみをサポートします。このスコープを使用したユーザー認証情報やドメイン全体の委任で認証することはできません。

機密性の高いスコープ

スコープコード 説明
https://www.googleapis.com/auth/chat.spaces Chat での会話とスペースの作成、メタデータ（履歴設定やアクセス設定を含む）の参照または編集を行います。
https://www.googleapis.com/auth/chat.spaces.create Chat で新しい会話を作成します。
https://www.googleapis.com/auth/chat.spaces.readonly Chat でチャットとスペースを表示します。
https://www.googleapis.com/auth/chat.memberships Chat の会話のメンバーを参照、追加、更新、削除する。
https://www.googleapis.com/auth/chat.memberships.app Google Chat の会話への追加と削除ができます。
https://www.googleapis.com/auth/chat.memberships.readonly Chat の会話のメンバーを表示する。
https://www.googleapis.com/auth/chat.messages.create Chat でメッセージを作成して送信します。
https://www.googleapis.com/auth/chat.messages.reactions Chat でメッセージへのリアクションを表示、追加、削除します。
https://www.googleapis.com/auth/chat.messages.reactions.create Chat でメッセージにリアクションを追加します。
https://www.googleapis.com/auth/chat.messages.reactions.readonly Chat でメッセージへのリアクションを表示します。
https://www.googleapis.com/auth/chat.users.readstate Chat の会話の最終既読時間の表示と変更を行います。
https://www.googleapis.com/auth/chat.users.readstate.readonly Chat の会話が最後に読まれた時間を確認します。
https://www.googleapis.com/auth/chat.admin.spaces.readonly Chat で、管理者のドメインが所有するチャットとスペースを表示します。
https://www.googleapis.com/auth/chat.admin.spaces Chat で管理者のドメインが所有するチャットとスペースを表示または編集します。
https://www.googleapis.com/auth/chat.admin.memberships.readonly 管理者のドメインが所有する会話のメンバーと管理者を Chat で表示します。
https://www.googleapis.com/auth/chat.admin.memberships Chat で管理者のドメインが所有する会話のメンバーと管理者を参照、追加、更新、削除する。
https://www.googleapis.com/auth/chat.app.spaces

Chat での会話とスペースの作成、メタデータ（履歴設定やアクセス設定を含む）の参照、更新。管理者の承認が必要です。

このスコープは、サービス アカウントを使用したアプリの認証のみをサポートします。このスコープを使用したユーザー認証情報やドメイン全体の委任で認証することはできません。
https://www.googleapis.com/auth/chat.app.spaces.create

Chat で新しい会話とスペースを作成します。管理者の承認が必要です。

このスコープは、サービス アカウントを使用したアプリの認証のみをサポートします。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。
https://www.googleapis.com/auth/chat.app.memberships

Chat の会話とスペースのメンバーを参照、追加、更新、削除します。 管理者の承認が必要です。

このスコープは、サービス アカウントによるアプリ認証のみをサポートします。このスコープを使用したユーザー認証情報やドメイン全体の委任で認証することはできません。
https://www.googleapis.com/auth/chat.customemojis Chat でカスタム絵文字を参照、作成、削除します。
https://www.googleapis.com/auth/chat.customemojis.readonly Chat でカスタム絵文字を表示します。
https://www.googleapis.com/auth/chat.users.spacesettings Chat ユーザー スペースの設定を表示、更新します。

スペースのユーザー設定 API: getSpaceNotificationSetting、updateSpaceNotificationSetting をご覧ください。

制限付きのスコープ

スコープコード 説明
https://www.googleapis.com/auth/chat.delete 会話とスペースを削除し、Chat で関連するファイルへのアクセス権を削除します。
https://www.googleapis.com/auth/chat.import スペース、メッセージ、メンバーシップを Chat にインポートします。詳細については、Chat アプリにデータのインポートを承認するをご覧ください。
https://www.googleapis.com/auth/chat.messages メッセージの参照、作成、送信、更新、削除、メッセージに対するリアクションの追加、参照、削除。
https://www.googleapis.com/auth/chat.messages.readonly Chat でメッセージとリアクションを表示できます。
https://www.googleapis.com/auth/chat.admin.delete 管理者のドメインが所有する会話とスペースを削除し、Chat で関連するファイルへのアクセス権を削除します。
https://www.googleapis.com/auth/chat.app.delete

Chat で会話とスペースを削除し、関連するファイルへのアクセス権を削除します。管理者の承認が必要です。

このスコープは、サービス アカウントによるアプリ認証のみをサポートします。このスコープを使用したユーザー認証情報やドメイン全体の委任で認証することはできません。

上の表のスコープは、次の定義に従って感度を示しています。

アプリが他の Google API へのアクセスを必要とする場合は、それらのスコープも追加できます。Google API スコープの詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。

Google Workspace API のスコープの詳細については、OAuth 同意画面を設定し、スコープを選択するをご覧ください。

必要な認証の種類

Chat アプリが Chat API で認証と承認を行う方法は 2 つあります。

ユーザー認証
ユーザー認証を使用すると、Chat アプリはユーザーデータにアクセスし、ユーザーに代わって操作を完了できます。OAuth スコープは、承認されたデータとアクションを指定します。Chat アプリが管理者によってインストールされているか、ドメイン全体の委任が付与されている場合を除き、Chat アプリがユーザーに代わって初めてアクションを実行する際は、ユーザーが OAuth 同意画面を使用して Chat アプリを承認する必要があります。
アプリの認証

アプリ認証により、Chat アプリはサービス アカウントの認証情報を使用してデータにアクセスし、アプリ自体としてアクションを完了します。Chat アプリは独自の認証情報を使用してリソースにアクセスし、リソースを操作するため、エンドユーザーは Chat アプリの API 呼び出しを承認する必要はありません。また、アプリの承認をサポートする OAuth 認可スコープを OAuth 同意画面に追加することはできません。

アプリの認証をサポートする OAuth 認可スコープは 2 種類あります。

  • https://www.googleapis.com/auth/chat.bot: Chat アプリは、この承認スコープをサポートする Google Chat API メソッドを呼び出して、アクセス可能なリソース（エンドユーザーが Chat 用アプリを追加するスペース内のメッセージなど）を作成、更新、取得、一覧表示、削除できます。Chat アプリは、この承認スコープを自己付与できます。管理者またはエンドユーザーの承認は必要ありません。
  • https://www.googleapis.com/auth/chat.app.*（デベロッパー プレビュー）: これらのスコープを使用するには、管理者の 1 回限りの承認が必要です。管理者の承認を得るには、Google Workspace Marketplace 対応の OAuth クライアントを作成し、Google Workspace Marketplace SDK でアプリを構成して、Chat アプリのサービス アカウントを準備し、管理者の承認を得る必要があります。これらのスコープにより、Chat アプリは特定の Google Chat API メソッドを呼び出すことができます。たとえば、chat.app.spaces.create は、アプリが Chat スペースを作成することを許可します。

メソッドがユーザー認証とアプリ認証の両方をサポートしている場合、Chat API は、使用する認証タイプに応じて異なる結果を返します。

  • アプリの認証では、このメソッドは Chat 用アプリがアクセスできるリソースのみを返します。
  • ユーザー認証の場合、メソッドはユーザーがアクセスできるリソースのみを返します。

たとえば、アプリの承認を使用して spaces.list() メソッドを呼び出すと、Chat アプリがメンバーになっているスペースのリストが返されます。ユーザー承認を使用して spaces.list() を呼び出すと、ユーザーがメンバーになっているスペースのリストが返されます。実際には、Chat アプリの設計と機能に応じて、Chat API を呼び出すときに両方のタイプの認証を使用できます。

非同期 Chat API 呼び出しの場合

次の表に、Chat API メソッドと、サポートされている認可スコープを示します。

メソッド ユーザー認証をサポート アプリ認証がサポートされている サポートされている認可スコープ
スペース  
スペースを作成する ユーザー認証の場合:
  • chat.spaces.create
  • chat.spaces
  • chat.import
アプリ認証と管理者の承認（デベロッパー プレビューで利用可能）:
  • chat.app.spaces.create
  • chat.app.spaces
スペースを設定する — ユーザー認証の場合:
  • chat.spaces.create
  • chat.spaces
スペースを取得する [ユーザー認証] の場合:
  • chat.spaces.readonly
  • chat.spaces
管理者権限を使用したユーザー認証の場合:
  • chat.admin.spaces.readonly
[アプリ認証] を使用する場合:
  • chat.bot
アプリ認証と管理者の承認（デベロッパー プレビューで利用可能）:
  • chat.app.spaces
スペースを一覧表示する ユーザー認証の場合:
  • chat.spaces.readonly
  • chat.spaces
アプリ認証を使用する場合:
  • chat.bot
検索スペース — 管理者権限を使用したユーザー認証の場合:
  • chat.admin.spaces.readonly
スペースを更新する ユーザー認証の場合:
  • chat.spaces
  • chat.import
管理者権限を使用したユーザー認証の場合:
  • chat.admin.spaces
アプリ認証と管理者の承認（デベロッパー プレビューで利用可能）:
  • chat.app.spaces
スペースを削除する ユーザー認証の場合:
  • chat.delete
  • chat.import
管理者権限を使用したユーザー認証の場合:
  • chat.admin.delete
アプリの認証と管理者による承認を使用する場合（デベロッパー プレビューで利用可能）:
  • chat.app.delete
スペースのインポート プロセスを完了する — ユーザー認証の場合:
  • chat.import
ダイレクト メッセージを探す ユーザー認証の場合:
  • chat.spaces.readonly
  • chat.spaces
アプリ認証を使用する場合:
  • chat.bot
メンバー  
メンバーを作成する ユーザー認証の場合:
  • chat.memberships
  • chat.memberships.app
  • chat.import
管理者権限を使用したユーザー認証の場合:
  • chat.admin.memberships
アプリ認証と管理者の承認（デベロッパー プレビューで利用可能）:
  • chat.app.memberships
メンバーを取得する ユーザー認証の場合:
  • chat.memberships.readonly
  • chat.memberships
アプリ認証を使用する場合:
  • chat.bot
管理者権限を使用したユーザー認証の場合:
  • chat.admin.memberships.readonly
メンバーを一覧表示する ユーザー認証の場合:
  • chat.memberships.readonly
  • chat.memberships
  • chat.import
アプリ認証を使用する場合:
  • chat.bot
管理者権限を使用したユーザー認証の場合:
  • chat.admin.memberships.readonly
メンバーを削除する ユーザー認証の場合:
  • chat.memberships
  • chat.memberships.app
  • chat.import
管理者権限を使用したユーザー認証の場合:
  • chat.admin.memberships
アプリ認証と管理者の承認（デベロッパー プレビューで利用可能）:
  • chat.app.memberships
メンバーを更新する ユーザー認証の場合:
  • chat.memberships
  • chat.import
管理者権限を使用したユーザー認証の場合:
  • chat.admin.memberships
アプリの認証と管理者による承認を使用する場合（デベロッパー プレビューで利用可能）:
  • chat.app.memberships
メッセージ  
メッセージを作成する [ユーザー認証] の場合:
  • chat.messages.create
  • chat.messages
  • chat.import
アプリ認証を使用する場合:
  • chat.bot
メッセージを取得する ユーザー認証の場合:
  • chat.messages.readonly
  • chat.messages
アプリ認証を使用する場合:
  • chat.bot
メッセージを一覧表示する — [ユーザー認証] の場合:
  • chat.messages.readonly
  • chat.messages
  • chat.import
メッセージを更新する ユーザー認証の場合:
  • chat.messages
  • chat.import
アプリ認証を使用する場合:
  • chat.bot
メッセージを削除する ユーザー認証の場合:
  • chat.messages
  • chat.import
アプリ認証を使用する場合:
  • chat.bot
リアクション  
リアクションを作成する — ユーザー認証の場合:
  • chat.messages.reactions.create
  • chat.messages.reactions
  • chat.messages
  • chat.import
リアクションを一覧表示する — ユーザー認証の場合:
  • chat.messages.reactions.readonly
  • chat.messages.reactions
  • chat.messages.readonly
  • chat.messages
リアクションを削除する — [ユーザー認証] の場合:
  • chat.messages.reactions
  • chat.messages
  • chat.import
カスタム絵文字  
カスタム絵文字を作成する — ユーザー認証の場合:
  • chat.customemojis
カスタム絵文字を削除する — ユーザー認証の場合:
  • chat.customemojis
カスタム絵文字を入手する — ユーザー認証の場合:
  • chat.customemojis
  • chat.customemojis.readonly
カスタム絵文字を一覧表示する — ユーザー認証の場合:
  • chat.customemojis
  • chat.customemojis.readonly
メディアと添付ファイル  
ファイルを添付ファイルとしてアップロードする — ユーザー認証の場合:
  • chat.messages.create
  • chat.messages
  • chat.import
メディアをダウンロードする ユーザー認証の場合:
  • chat.messages.readonly
  • chat.messages
[アプリ認証] を使用する場合:
  • chat.bot
メッセージのアタッチメントを取得する — [アプリ認証] の場合:
  • chat.bot
ユーザーの読み取り状態
ユーザーのスペース読み取り状態を取得する — [ユーザー認証] の場合:
  • chat.users.readstate
  • chat.users.readstate.readonly
ユーザーのスペース読み取り状態を更新する — [ユーザー認証] の場合:
  • chat.users.readstate
ユーザーのスレッドの読み取り状態を取得する — ユーザー認証の場合:
  • chat.users.readstate
  • chat.users.readstate.readonly
ユーザー空間の設定
ユーザーのスペースの通知設定を取得する — ユーザー認証の場合:
  • chat.users.spacesettings
ユーザーのスペースの通知設定を更新する — ユーザー認証の場合:
  • chat.users.spacesettings
スペース イベント
スペースのイベントを取得する — ユーザー認証では、イベントタイプに基づいてスコープを使用する必要があります。
  • メッセージに関するイベントの場合:
    • chat.messages
    • chat.messages.readonly
  • リアクションに関するイベントの場合:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • メンバーシップに関するイベントの場合:
    • chat.memberships
    • chat.memberships.readonly
  • スペースに関するイベントの場合:
    • chat.spaces
    • chat.spaces.readonly
スペースのイベントを一覧表示する — ユーザー認証では、リクエストに含まれるイベントタイプごとにスコープを使用する必要があります。
  • メッセージに関するイベントの場合:
    • chat.messages
    • chat.messages.readonly
  • リアクションに関するイベントの場合:
    • chat.messages.reactions
    • chat.messages.reactions.readonly
    • chat.messages
    • chat.messages.readonly
  • メンバーシップに関するイベントの場合:
    • chat.memberships
    • chat.memberships.readonly
  • スペースに関するイベントの場合:
    • chat.spaces
    • chat.spaces.readonly

Chat アプリのインタラクション イベントの場合

次の表に、ユーザーが Chat アプリを操作する一般的な方法と、認証が必須かサポートされているかを示します。

シナリオ 認証は不要 ユーザー認証をサポート アプリの認証のサポート
次のユーザーからメッセージを受信する:
Chat アプリのインタラクション イベント — —
Apps Script コールバック — —
Google Cloud Pub/Sub — —
メッセージに返信する:
同期的に、Chat アプリのインタラクション イベントを使用 — —
同期的に、Apps Script コールバックの戻り値を使用する — —
新しいメッセージを送信する:
着信 Webhook を使用する場合 — —