認証と認可は、それぞれ ID の検証とリソースへのアクセスに使用されるメカニズムです。このドキュメントでは、Chat アプリと Chat API リクエストの認証と認可の仕組みについて概説します。
プロセスの概要
次の図は、Google Chat の認証と認可の大まかな手順を示しています。
Google Cloud プロジェクトを構成し、Chat API を有効にして、Chat アプリを構成する: 開発中に、Google Cloud プロジェクトを作成します。Google Cloud プロジェクトで、Chat API を有効にし、Chat アプリを構成して、認証を設定します。詳しくは、Google Workspace で開発するとChat アプリを作成するをご覧ください。
Chat API を呼び出す: アプリが Chat API を呼び出すと、認証情報は Chat API に送信されます。アプリがサービス アカウントで認証する場合、認証情報はアプリのコードとともに送信されます。アプリで、まだ付与されていないユーザーの認証を使用して Chat API を呼び出す必要がある場合は、ログインを促すメッセージがユーザーに表示されます。
リソースをリクエストする: アプリが、認証の設定時に指定したスコープでのアクセスを要求します。
同意を求める: アプリがユーザーとして認証されている場合、OAuth 同意画面が表示されます。これにより、ユーザーはリクエストされたデータへのアクセスをアプリに許可するかどうかを決定できます。サービス アカウントによる認証には、ユーザーの同意は必要ありません。
リソースの承認済みリクエストを送信する: ユーザーが認可スコープに同意すると、アプリは認証情報とユーザーが承認したスコープをリクエストにバンドルします。アクセス トークンを取得するために、リクエストが Google の承認サーバーに送信されます。
Google がアクセス トークンを返します。アクセス トークンには、付与されたスコープのリストが含まれています。返されたスコープのリストがリクエストされたスコープよりも制限が厳しい場合、アプリはトークンによって制限されたすべての機能をオフにします。
リクエストされたリソースにアクセスする: アプリは Google のアクセス トークンを使用して Chat API を呼び出し、Chat API リソースにアクセスします。
更新トークンを取得する（省略可）: アプリが 1 つのアクセス トークンの有効期間を超えて Google Chat API にアクセスする必要がある場合は、更新トークンを取得できます。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。
リソースの追加をリクエストする: アプリに追加のアクセス権が必要な場合は、新しいスコープを付与するようユーザーに求めるメッセージが表示され、アクセス トークンを取得するための新しいリクエストが行われます（手順 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 アプリ間のリクエスト / レスポンスのシーケンスを示しています。
- ユーザーが 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 - 認可アクセスの範囲が最も小さく、基本的なアプリ確認のみが必要です。この要件の詳細については、検証の準備手順をご覧ください。
Sensitive - これらのスコープにより、アプリから特定のユーザーの Google データへのアクセス権をユーザーから受けた後で使用できるようになります。そのため、追加のアプリ検証を行う必要があります。この要件の詳細については、機密性の高いスコープをリクエストするアプリの手順をご覧ください。
制限付き - これらのスコープは Google のユーザーデータへの幅広いアクセスを可能にします。制限付きスコープの確認プロセスを完了する必要があります。この要件については、Google API サービス: ユーザーデータ ポリシーと特定の API スコープの追加要件をご覧ください。制限付きスコープをリクエストするアプリの手順もご覧ください。
アプリが他の 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 アプリのインタラクション イベントの場合
次の表に、ユーザーが Chat アプリを操作する一般的な方法と、認証が必須かサポートされているかを示します。
| シナリオ | 認証は不要 | ユーザー認証をサポート | アプリの認証のサポート | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 次のユーザーからメッセージを受信する: |
|
|||||||||||||||
| メッセージに返信する: |
|
|||||||||||||||
| 新しいメッセージを送信する: |
|
|||||||||||||||
関連トピック
- Google Workspace での認証と認可の概要については、認証と認可についてをご覧ください。
- Google Cloud での認証と認可の概要については、認証の概要をご覧ください。
- サービス アカウントの詳細については、サービス アカウントをご覧ください。
- Google API が OAuth 2.0 を使用する方法の詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と承認を設定します。