開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーに Box 内のファイルやフォルダへのアクセス権限が付与されるしくみと同様、アプリケーションにも、Box ユーザーや Box を使用する企業に代わって特定のアクションを実行するための独自の権限が付与されます。アプリケーションに対する権限セットの名前を「スコープ」と言います。つまり、アプリケーションのスコープにより、アプリケーションから呼び出すことのできるエンドポイントが決まります。また、このスコープは、アプリケーションのアクセストークンが提供するアクセス権限に反映されます。
ユーザー権限とスコープ
アクションを実行するための適切なスコープがアプリケーションに設定されている場合でも、アクセストークンと関連付けられた、呼び出しを実行するユーザーにはそのアクションを実行するための権限が必要であり、逆の場合も同様であることを理解することが重要です。
たとえば、ファイルを読み取るようにアプリケーションが設定されている場合、アクセスしようとするファイルの読み取り権限が認証済みユーザーにも必要です。
スコープ、トークンの権限、ユーザー権限がどのように連携しているかの詳細については、Box のセキュリティガイドを参照してください。
スコープと OAuth 2 承認
アプリケーションを承認するためにクライアント側の OAuth 2 フローを介してユーザーを送信する際は、承認 URL に一連のスコープを追加してユーザーのアクセストークンをさらに制限できます。
たとえば、アプリケーションでroot_readonlyおよびroot_readwriteスコープが有効になっている場合は、ユーザーのリダイレクト時にこのスコープを指定することで、ユーザーのアクセストークンをroot_readonlyに制限できます。
GET https://account.box.com/api/oauth2/authorize?scope=root_readonly&client_id=....
セルフサービススコープ
これらのスコープは、アプリケーションの設定時に開発者コンソールから使用できます。[構成] タブの [アプリケーションスコープ] セクションに移動して、以下のスコープから 1 つ以上を選択します。
すべてのファイルとフォルダの読み取り
| |
|---|
| OAuth スコープ | root_readonly |
| アプリケーションスコープ | Box に格納されているすべてのファイルとフォルダの読み取り |
as-userヘッダーを使用するか、ユーザーアクセストークンを作成する必要があります。
すべてのファイルとフォルダの読み取りと書き込み
| |
|---|
| OAuth スコープ | root_readwrite |
| アプリケーションスコープ | Box に格納されているすべてのファイルとフォルダの読み取りと書き込み |
ユーザーを管理する
開発者コンソールにある「ユーザーを管理する」スコープは、2 つの OAuth スコープにマップされます。
| |
|---|
| OAuth スコープ | manage_managed_users |
| アプリケーションスコープ | ユーザーを管理する |
これを使用すると、アプリケーションでユーザーを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。さらに、JWT アプリケーションの場合は、アプリケーションアクセスを [アプリアクセス + Enterprise アクセス] にしてアプリケーションを設定する必要があります。 | |
|---|
| OAuth スコープ | manage_app_users |
| アプリケーションスコープ | ユーザーを管理する |
グループを管理する
| |
|---|
| OAuth スコープ | manage_groups |
| アプリケーションスコープ | グループを管理する |
これを使用すると、アプリケーションでグループを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。さらに、JWT アプリケーションの場合は、アプリケーションアクセスを [アプリアクセス + Enterprise アクセス] にしてアプリケーションを設定する必要があります。 Webhook を管理する
| |
|---|
| OAuth スコープ | manage_webhook |
| アプリケーションスコープ | Webhook を管理する |
Enterprise のプロパティを管理する
| |
|---|
| OAuth スコープ | manage_enterprise_properties |
| アプリケーションスコープ | Enterprise のプロパティを管理する |
これを使用すると、アプリケーションで企業のプロパティを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。
リテンションポリシーを管理する
| |
|---|
| OAuth スコープ | manage_data_retention |
| アプリケーションスコープ | リテンションポリシーを管理する |
| 依存先 | enterprise_contentスコープ |
このスコープを使用するには、enterprise_contentスコープも適切に機能する必要があります。これらのスコープをリクエストするには、当社のサポートチャネルでチケットを作成します。
署名リクエストを管理する
| |
|---|
| OAuth スコープ | sign_requests.readwrite |
| アプリケーションスコープ | 署名リクエストを管理する |
Box AI API を管理する
| |
|---|
| OAuth スコープ | ai.readwrite |
| アプリケーションスコープ | AI を管理する |
Box Relay を管理する
| |
|---|
| OAuth スコープ | manage_triggers |
| アプリケーションスコープ | Box Relay を管理する |
WORKFLOW_MANUAL_STARTタイプのフローを開始するための権限が付与されます。
このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。
リクエストに応じて使用可能
リクエスト時にのみ使用できる追加のスコープがいくつかあります。これを使用するには、Box のサポートチームにチケットを送信してください。サポートチームは、個別にリクエストを確認し、ユースケースにスコープが必要な場合にのみ承認を行います。
リーガルホールドを管理する
| |
|---|
| OAuth スコープ | manage_legal_holds |
| アプリケーションスコープ | リテンションポリシーを管理する |
| 依存先 | enterprise_contentスコープ |
このスコープが適切に機能するには、enterprise_contentスコープを必要とします。このスコープは、当社のサポートチャネルでチケットを作成してリクエストできます。
メール通知を抑制する
| |
|---|
| アプリケーションスコープ | API コールからメール通知を抑制する |
グローバルコンテンツマネージャ (GCM)
| |
|---|
| OAuth スコープ | enterprise_content |
| アプリケーションスコープ | グローバルコンテンツマネージャ |
副次的影響アプリケーションに対してこのスコープを有効にすると、一部の API コールの動作が変更されます。その最も顕著な例として、as-userヘッダーを使用してユーザーとして明示的に認証しないとコンテンツを書き込めなくなることが挙げられます。また、このスコープを有効にすると、別の企業のユーザーが所有するコンテンツにはアクセスできなくなります。そのため、やむを得ない場合を除き、このスコープはプロビジョニングされません。
ダウンスコープ用のスコープ
特にトークンをクライアント側 (ブラウザなどの公開された環境) に公開する必要がある場合など、アクセストークンをより厳格な権限レベルにダウンスコープしなければならないことがあります。その主な例として、ユーザーのブラウザでアクセストークンが必要となるBox UI Elementsを使用する場合が挙げられます。
既存のアクセストークンをダウンスコープするためにPOST /oauth2/tokenエンドポイントで使用できる追加のスコープのリストを以下に示します。
| OAuth スコープ | 影響を受ける UI Element | 説明 |
|---|
annotation_edit | プレビュー | 注釈の編集と削除をユーザーに許可します。 |
annotation_view_all | プレビュー | すべてのユーザーによる注釈の表示をユーザーに許可します。 |
annotation_view_self | プレビュー | ユーザーに自分の注釈のみの表示を許可します。 |
base_explorer | Explorer | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 |
base_picker | Picker | ユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。 |
base_preview | プレビュー | ファイルのプレビューのみをユーザーに許可します。 |
base_sidebar | Sidebar | サイドバー UI Element に必要なファイルの基本情報の取得をユーザーに許可します。 |
base_upload | Uploader | トークンのダウンスコープ時に、resourceの下で指定されたフォルダへのアップロードを許可します。 |
item_delete | Explorer | ファイルとフォルダの削除を許可します。 |
item_download | Explorer、Preview | ファイルまたはフォルダのコンテンツのダウンロードを許可します。 |
item_preview | Explorer | ファイルのプレビューを有効にします。 |
item_rename | Explorer | ファイルとフォルダの名前変更を許可します。 |
item_share | Explorer、Picker | トークン交換のresourceで指定された項目の共有を許可します。 |
item_upload | Picker | Content Picker でのアップロードを許可します。 |
| OAuth スコープ | 説明 |
|---|
ai.readwrite | AI API を管理する |
manage_managed_users | 管理対象ユーザーを管理する |
manage_app_users | App User を管理 |
manage_data_retention | リテンションポリシーを管理する |
manage_enterprise_properties | Enterprise のプロパティを管理する |
manage_groups | グループを管理する |
manage_webhook | Webhook を管理する |
sign_requests.readwrite | 署名リクエストを管理する |
