認証と認可は、それぞれ 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 を呼び出す必要がある場合は、ユーザーにログインを求めます。
リソースのリクエスト: アプリは、認証の設定時に指定したスコープを使用したアクセス権を要求します。
同意の確認: アプリがユーザーとして認証されている場合、Google は OAuth 同意画面を表示します。ユーザーはこの画面で、リクエストされたデータへのアクセスをアプリに許可するかどうかを選択できます。サービス アカウントによる認証では、ユーザーの同意は必要ありません。
リソースに対する承認済みのリクエストを送信する: ユーザーが承認スコープに同意すると、アプリは認証情報とユーザー承認のスコープをリクエストにバンドルします。リクエストは 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 リクエストを行います。これには認証と認可が必要です。
ユーザー操作に対するレスポンスには認証は不要
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 同意画面を構成し、スコープを選択して、ユーザーとアプリの審査担当者に表示する情報を定義し、後で公開できるようにアプリを登録します。
アプリに付与されるアクセスレベルを定義するには、認可スコープを特定して宣言する必要があります。認可スコープは OAuth 2.0 URI 文字列で、Google Workspace アプリ名、アクセスするデータの種類、アクセスレベルが含まれます。
機密性の低いスコープ
| スコープコード | 説明 |
|---|---|
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.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 内の関連ファイルへのアクセス権を削除します。 |
上の表のスコープは、次の定義に従って機密性を示しています。
機密性なし - 承認アクセスの最小範囲を提供するスコープで、基本的なアプリ検証のみが必要です。この要件の詳細については、検証の準備手順をご覧ください。
機密 - このスコープを使用すると、ユーザーから承認を得た後に、アプリが特定のユーザーの 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 へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と認可を設定します。