認証と認可は、それぞれ 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 リクエストを行います。このリクエストには認証と承認が必要です。
ユーザー操作に対するレスポンスで認証が不要
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 で会話とスペースを削除し、関連するファイルへのアクセス権を削除します。管理者の承認が必要です。 このスコープは、サービス アカウントによるアプリ認証のみをサポートします。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
上の表のスコープは、次の定義に従って感度を示しています。
非機密 - これらのスコープは、認可アクセスの範囲が最も狭く、基本的なアプリの検証のみが必要です。この要件については、確認の準備手順をご覧ください。
機密性の高い - これらのスコープを使用すると、ユーザーから承認を得た後、アプリは特定のユーザーの 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 へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と承認を設定します。