認証と認可は、ID とリソースへのアクセスのそれぞれを確認するために使用されるメカニズムです。このドキュメントでは、Chat アプリと Chat API リクエストの認証と認可の仕組みについて概説します。
プロセスの概要
次の図は、Google Chat の認証と認可の概要を示しています。
Google Cloud プロジェクトを構成し、Chat API を有効にして Chat アプリを構成する: 開発中に Google Cloud プロジェクトを作成します。Google Cloud プロジェクトで、Chat API を有効にし、Chat アプリを構成して、認証を設定します。詳しくは、Google Workspace で開発するとChat アプリを作成するをご覧ください。
Call Chat API: アプリが Chat API を呼び出すと、Chat API に認証情報が送信されます。アプリがサービス アカウントを使用して認証される場合、認証情報はアプリのコードの一部として送信されます。アプリでまだ付与されていないユーザーの認証を使用して Chat API を呼び出す必要がある場合は、ユーザーにログインを求めます。
リソースをリクエストする: アプリは、認証の設定時に指定したスコープを使用してアクセスをリクエストします。
同意を求める: アプリがユーザーとして認証されている場合、Google は OAuth 同意画面を表示します。ユーザーは、リクエストされたデータへのアクセス権をアプリに許可するかどうかを判断できます。サービス アカウントによる認証では、ユーザーの同意は必要ありません。
リソースの承認済みリクエストを送信する: ユーザーが承認スコープに同意すると、アプリは認証情報とユーザーが承認したスコープを 1 つのリクエストにバンドルします。アクセス トークンを取得するために、リクエストが Google の承認サーバーに送信されます。
Google がアクセス トークンを返します。アクセス トークンには、付与されたスコープのリストが含まれています。返されたスコープのリストがリクエストされたスコープよりも制限が厳しい場合、アプリはトークンによって制限されたすべての機能をオフにします。
リクエストされたリソースにアクセスする: アプリは Google のアクセス トークンを使用して Chat API を呼び出し、Chat API リソースにアクセスします。
更新トークンを取得する（省略可）: アプリが 1 つのアクセス トークンの有効期間を超えて Google Chat API にアクセスする必要がある場合は、更新トークンを取得できます。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。
リソースの追加をリクエストする: アプリに追加のアクセス権が必要な場合は、新しいスコープを付与するようユーザーに求めるメッセージが表示され、アクセス トークンを取得するための新しいリクエストが行われます（手順 3～6）。
Chat アプリで認証が必要な場合
チャットアプリは、ユーザー操作に応じて、または非同期でメッセージを送信できます。また、Chat スペースの作成や Chat スペース内のユーザーのリスト取得など、ユーザーに代わってタスクを完了することもできます。
Chat アプリがレスポンスの処理中に Chat API または別の Google API を呼び出す場合を除き、ユーザー操作に応答するために認証は必要ありません。
非同期メッセージを送信したり、ユーザーに代わってタスクを実行したりするために、Chat アプリは Chat API に対して RESTful リクエストを行います。このリクエストには認証と承認が必要です。
ユーザー操作に対するレスポンスに認証を必要としない
Google Chat アプリでは、インタラクション イベントを受信して同期的に応答するために、ユーザーまたは Chat アプリとして認証する必要はありません。
Google Chat アプリは、ユーザーが Chat 用アプリを操作するか呼び出すたびに、次のようなインタラクション イベントを受け取ります。
- ユーザーが Chat アプリにメッセージを送信します。
- ユーザーが Chat 用アプリに @メンションしました。
- ユーザーが Chat アプリのスラッシュ コマンドのいずれかを呼び出します。
次の図は、Chat ユーザーと Chat アプリ間のリクエスト / レスポンスのシーケンスを示しています。
- ユーザーが Google Chat の Chat アプリにメッセージを送信します。
- Google Chat からアプリにメッセージが転送されます。
- アプリはメッセージを受信して処理し、Google Chat にレスポンスを返します。
- Google Chat によって、ユーザーまたはスペース内に回答が表示されます。
このシーケンスは、Chat アプリのインタラクション イベントごとに繰り返されます。
非同期メッセージには認証が必要
非同期メッセージは、Chat アプリが Chat API にリクエストを送信するときに発生します。このリクエストには認証と承認が必要です。
Chat API を呼び出すと、Chat アプリから Google Chat にメッセージを投稿したり、ユーザーの代わりにタスクを完了してデータにアクセスしたりできます。たとえば、サーバーの停止を検出すると、Chat アプリは Chat API を呼び出して次のことができます。
- サービス停止の調査と修正専用の Chat スペースを作成します。
- Chat スペースにユーザーを追加する。
- Chat スペースにメッセージを投稿して、サービス停止の詳細を伝えます。
次の図は、Chat アプリと Chat スペース間の非同期メッセージ シーケンスを示しています。
- Chat アプリは、
spaces.messages.createメソッドを使用して Chat API を呼び出してメッセージを作成し、HTTP リクエストにユーザー認証情報を含めます。 - Google Chat は、サービス アカウントまたはユーザーの認証情報を使用して Chat アプリを認証します。
- 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 で会話とスペースを削除し、関連するファイルへのアクセス権を削除します。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリの認証のみをサポートします。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
上の表のスコープは、次の定義に従って機密性を示しています。
Non-sensitive - 認可アクセスの範囲が最も小さく、基本的なアプリ確認のみが必要です。この要件については、確認の準備手順をご覧ください。
機密性の高いスコープ - これらのスコープを使用すると、ユーザーから承認を得た後、特定のユーザーの Google データにアプリがアクセスできるようになります。そのため、追加のアプリ検証を行う必要があります。この要件の詳細については、機密性の高いスコープをリクエストするアプリの手順をご覧ください。
制限付き - これらのスコープは Google のユーザーデータへの幅広いアクセスを可能にします。制限付きスコープの確認プロセスを完了する必要があります。この要件について詳しくは、Google API サービス: ユーザーデータ ポリシーと特定の API スコープの追加要件をご覧ください。制限付きスコープをリクエストするアプリ向けの手順もご覧ください。
アプリが他の Google API へのアクセスを必要とする場合は、それらのスコープも追加できます。Google API スコープの詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
Google Workspace API のスコープの詳細については、OAuth 同意画面を設定し、スコープを選択するをご覧ください。
必要な認証の種類
Chat アプリは、次の 2 つの方法で Chat API を使用して認証と認可を行うことができます。
- ユーザー認証
- ユーザー認証を使用すると、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 アプリのインタラクション イベントの場合
次の表に、ユーザーが Chat アプリを操作する一般的な方法と、認証が必須かサポートされているかを示します。
| シナリオ | 認証は不要 | ユーザー認証のサポート | アプリ認証がサポートされている | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 次のユーザーからメッセージを受信する: |
|
|||||||||||||||
| メッセージに返信する: |
|
|||||||||||||||
| 新しいメッセージを送信する: |
|
|||||||||||||||
関連トピック
- Google Workspace での認証と認可の概要については、認証と認可についてをご覧ください。
- Google Cloud での認証と認可の概要については、認証の概要をご覧ください。
- サービス アカウントの詳細については、サービス アカウントをご覧ください。
- Google API が OAuth 2.0 を使用する方法の詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と認可を設定します。