認証と認可は、それぞれ 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 リソースにアクセスします。
更新トークンを取得する（省略可）: アプリが 1 つのアクセス トークンの有効期間を超えて Google Chat API にアクセスする必要がある場合は、更新トークンを取得できます。詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。
追加のリソースをリクエストする: アプリが追加のアクセスを必要とする場合、ユーザーに新しいスコープを付与するようリクエストします。これにより、アクセス トークンを取得するための新しいリクエストが生成されます（ステップ 3 ～ 6）。
Chat 用アプリで認証が必要な場合
Chat 用アプリは、ユーザー インタラクションに応じて、または非同期でメッセージを送信できます。また、Chat スペースの作成や Chat スペース内のユーザーのリストの取得など、ユーザーに代わってタスクを完了することもできます。
Chat 用アプリがレスポンスの処理中に Chat API または別の Google API を呼び出さない限り、Chat 用アプリはユーザー操作に応答するために認証を必要としません。
非同期メッセージを送信したり、ユーザーに代わってタスクを実行したりするには、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 用アプリは、Chat API を呼び出すことで、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 用アプリとして、Chat での会話やスペースの作成とメタデータ（履歴設定やアクセス設定を含む）の表示または更新。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリ認証のみをサポートしています。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
https://www.googleapis.com/auth/chat.app.spaces.readonly
|
Chat 用アプリとして Chat のメタデータ（履歴設定を含む）を表示します。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリ認証のみをサポートしています。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Chat 用アプリとして Chat で新しい会話やスペースを作成します。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリ認証のみをサポートしています。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
https://www.googleapis.com/auth/chat.app.memberships
|
Chat 用アプリとして、Chat での会話やスペースのメンバーの表示、追加、更新、削除を行います。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリ認証のみをサポートしています。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
https://www.googleapis.com/auth/chat.app.memberships.readonly
|
Chat 用アプリとして、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 ユーザーのスペース設定を表示、更新します。 |
https://www.googleapis.com/auth/chat.users.sections
|
Chat でセクションを参照、作成、更新、削除する。Chat でセクション アイテムを移動、一覧参照する。 |
https://www.googleapis.com/auth/chat.users.sections.readonly
|
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.app.messages.readonly
|
Chat アプリとして Chat のメッセージとリアクションを表示します。管理者の承認が必要です。 このスコープは、サービス アカウントを使用したアプリ認証のみをサポートしています。このスコープを使用して、ユーザー認証情報またはドメイン全体の委任で認証することはできません。 |
https://www.googleapis.com/auth/chat.admin.delete
|
管理者のドメインが所有する会話とスペース、関連ファイルへのアクセス権を Chat で削除する。 |
https://www.googleapis.com/auth/chat.app.delete
|
Chat 用アプリとして、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 へのアクセスをご覧ください。
- ユーザー認証情報またはサービス アカウントを使用して認証と認可を設定します。
- きめ細かな OAuth 権限を管理するには、Google Chat アプリのきめ細かな OAuth 権限を管理するをご覧ください。