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. 同意を求める: アプリがユーザーとして認証される場合、Google は OAuth 同意画面を表示します。ユーザーは、リクエストされたデータへのアクセス権限をアプリに付与するかどうかを決定できます。サービス アカウントによる認証では、ユーザーの同意は必要ありません。

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

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

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

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

  9. リソースの追加をリクエストする: アプリでより多くのアクセスが必要な場合は、ユーザーに新しいスコープの付与を求め、アクセス トークンを取得するための新しいリクエストが生成されます（手順 3 ～ 6）。

Chat 用アプリで認証が必要な場合

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

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

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

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

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 アプリとして、Chat で会話やスペースを作成し、メタデータ（履歴設定やアクセス設定を含む）を表示または更新します。管理者の承認が必要です。

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

Chat アプリとして Chat で新しい会話とスペースを作成します。管理者による承認が必要です。

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

Chat アプリとして、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 ユーザーのスペース設定を表示、更新します。

制限付きのスコープ

スコープコード 説明
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.app.messages.readonly

Chat アプリとして Chat のメッセージとリアクションを表示します。 管理者による承認が必要です。

このスコープは、サービス アカウントを使用したアプリ認証のみをサポートします。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。
https://www.googleapis.com/auth/chat.admin.delete 管理者のドメインが所有する会話とスペース、関連ファイルへのアクセス権を Chat で削除します。
https://www.googleapis.com/auth/chat.app.delete

Chat 用アプリとして、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.app.messages.readonly
メッセージを一覧表示する ユーザー認証の場合:
  • chat.messages.readonly
  • chat.messages
  • chat.import
アプリ認証と管理者による承認（デベロッパー プレビューで利用可能）の場合:
  • chat.app.messages.readonly
メッセージを更新する ユーザー認証の場合:
  • 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
Space イベント
スペースのイベントを取得する — ユーザー認証では、 イベントタイプに基づくスコープを使用する必要があります。
  • メッセージに関するイベントの場合:
    • 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 を使用する — —