認証と認可は、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 リソースにアクセスします。
更新トークンを取得する（省略可）: 単一のアクセス トークンの有効期間を超えて Google Chat API にアクセスする必要がある場合、アプリは更新トークンを取得できます。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。
リソースの追加リクエスト: アプリがさらにアクセス権を必要とする場合、新しいスコープを付与するようユーザーに求め、アクセス トークンを取得するための新しいリクエストが送信されます（ステップ 3 ～ 6）。
Chat アプリで認証が必要な場合
Chat アプリは、ユーザーの操作に応じてメッセージを送信することも、非同期でメッセージを送信することもできます。また、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 アプリでチャットの表示とメッセージの送信を許可します。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.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 内の関連ファイルへのアクセス権を削除します。 |
上の表のスコープは、次の定義に従って機密性を示しています。
非機密 - これらのスコープは認可アクセスの範囲を最小限に抑え、基本的なアプリ確認のみを必要とします。この要件の詳細については、検証の準備手順をご覧ください。
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 アプリはサービス アカウントの認証情報を使用して、アプリとして API にアクセスします。アプリの承認では、常に chat.bot 承認スコープが使用されます。
特定の API リクエストに使用する認証情報の種類を決定する際は、一部の API メソッドが特定の種類の認証情報のみをサポートしていることに注意してください。API メソッドが両方の認証情報をサポートしている場合、呼び出しで使用される認証情報のタイプによって、返される結果が異なります。
- アプリの承認を使用すると、メソッドはアプリがアクセスできるリソースのみを返します。
- ユーザー承認により、メソッドはユーザーが Chat UI でアクセスできるリソースのみを返します。
たとえば、アプリの承認を使用して ListSpaces メソッドを呼び出すと、アプリがメンバーとなっているスペースのリストが返されます。ユーザー承認を使用して ListSpaces を呼び出すと、ユーザーがメンバーになっているスペースのリストが返されます。実際には、必要な機能に応じて、アプリで Chat API を呼び出すときに両方のタイプの認可を使用できます。
非同期 Chat API 呼び出しの場合
次の表に、Chat API メソッドと、サポートされている承認スコープを示します。
| メソッド | ユーザー認証のサポート | アプリの認証のサポート | サポートされている認可スコープ | |
|---|---|---|---|---|
| スペース | ||||
| スペースを作成する | — |
[ユーザー認証] の場合:
|
||
| スペースを設定する | — |
[ユーザー認証] の場合:
|
||
| スペースを取得する |
[ユーザー認証] の場合:
|
|||
| スペースを一覧表示する |
[ユーザー認証] の場合:
|
|||
| スペースを検索 |
管理者権限を使用したユーザー認証の場合:
|
|||
| スペースを更新する | — |
[ユーザー認証] の場合:
|
||
| スペースを削除する | — |
[ユーザー認証] の場合:
|
||
| スペースのインポート プロセスを完了する | — |
[ユーザー認証] の場合:
|
||
| ダイレクト メッセージを見つける |
[ユーザー認証] の場合:
|
|||
| Members | ||||
| メンバーを作成する | — |
[ユーザー認証] の場合:
|
||
| メンバーを取得する |
[ユーザー認証] の場合:
|
|||
| メンバーを一覧表示する |
[ユーザー認証] の場合:
|
|||
| メンバーを削除する | — |
[ユーザー認証] の場合:
|
||
| メンバーを更新する | — |
[ユーザー認証] の場合:
|
||
| メッセージ | ||||
| メッセージを作成する |
[ユーザー認証] の場合:
|
|||
| メッセージを取得する |
[ユーザー認証] の場合:
|
|||
| メッセージを一覧表示する | — |
[ユーザー認証] の場合:
|
||
| メッセージを更新する |
[ユーザー認証] の場合:
|
|||
| メッセージを削除する |
[ユーザー認証] の場合:
|
|||
| リアクション | ||||
| リアクションを作成する | — |
[ユーザー認証] の場合:
|
||
| リアクションを一覧表示する | — |
[ユーザー認証] の場合:
|
||
| リアクションを削除する | — |
[ユーザー認証] の場合:
|
||
| メディアと添付ファイル | ||||
| メディアを添付ファイルとしてアップロードする | — |
[ユーザー認証] の場合:
|
||
| メディアをダウンロードする |
[ユーザー認証] の場合:
|
|||
| メッセージの添付ファイルを取得する | — |
[アプリ認証] の場合:
|
||
| ユーザーの読み取り状態 | ||||
| ユーザーのスペース読み取り状態を取得する | — |
[ユーザー認証] の場合:
|
||
| ユーザーのスペース読み取り状態を更新する | — |
[ユーザー認証] の場合:
|
||
| ユーザーのスレッドの読み取り状態を取得する | — |
[ユーザー認証] の場合:
|
||
| スペース イベント | ||||
| 宇宙のイベントを見る | — |
[ユーザー認証] の場合:
|
||
| スペースのイベントを一覧表示する | — |
[ユーザー認証] の場合:
|
||
Chat 用アプリのインタラクション イベントの場合
次の表に、ユーザーが Chat 用アプリを使用する一般的な方法と、認証が必要かサポートされているかを示します。
| シナリオ | 認証は不要 | ユーザー認証のサポート | アプリの認証のサポート | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 以下からのメッセージの受信元: |
|
|||||||||||||||
| メッセージに返信します。 |
|
|||||||||||||||
| 新しいメッセージを送信するには: |
|
|||||||||||||||
関連トピック
- Google Workspace での認証と認可の概要については、認証と認可の詳細をご覧ください。
- Google Cloud での認証と認可の概要については、認証の概要をご覧ください。
- サービス アカウントの詳細については、サービス アカウントをご覧ください。
- Google API による OAuth 2.0 の活用方法については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と認可を設定します。