スコープ

スコープ

重要なのは、開発者コンソールでBoxアプリケーションを設定するときに適切なスコープを選択してそのアプリケーションに対する適切な権限を選択することです。

スコープについて

ユーザーがBox内のファイルやフォルダなどの項目に対する特定のアクセス権限を持つように、アプリケーションも、BoxユーザーまたはBoxを使用する会社に代わって特定のアクションを実行するための権限を独自に持ちます。

アプリケーションに対する権限セットの名前を「スコープ」と言います。アプリケーションに適切なスコープを選択することで、ユーザーの特定のタスクをそのアプリケーションで実行できるほか、自分が意図しないタスクを実行しないようアプリケーションを制限することもできます。

ユーザー権限とスコープ

アクションを実行するための適切なスコープがアプリケーションに設定されている場合でも、API呼び出しで認証されたユーザーにはそのアクションを実行するための権限が必要であり、逆の場合も同様であることを理解することが重要です。

たとえば、ファイルを読み取るようにアプリケーションが設定されている場合、アクセスしようとするファイルの読み取り権限が認証済みユーザーにも必要です。

スコープとOAuth 2承認

アプリケーションを承認するためにクライアント側のOAuth 2フローを介してユーザーを送信する際は、承認URLに一連のスコープを追加してユーザーのアクセストークンをさらに制限できます。

たとえば、アプリケーションでroot_readonlyおよびroot_readwriteスコープが有効になっている場合は、ユーザーのリダイレクト時にこのスコープを指定することで、ユーザーのアクセストークンをroot_readonlyに制限できます。

GET https://account.box.com/api/oauth2/authorize?scope=root_readonly&client_id=....

スコープパラメータが省略されている場合、アプリケーションでは、そのアプリケーションの作成時に設定されたスコープが使用されます。

セルフサービススコープ

これらのスコープは、カスタムアプリケーションの設定時に開発者コンソールから使用できます。アプリケーション設定の[構成]ページにある[アプリケーションスコープ]セクションに移動して、以下のいずれかのスコープを選択します。

すべてのファイルとフォルダの読み取り

OAuthスコープroot_readonly
アプリケーションスコープBoxに格納されているすべてのファイルとフォルダの読み取り

アプリケーションで、認証済みユーザーはすべてのファイル/フォルダを読み取ることができるようになります。

これにより、アプリケーションにはファイルとフォルダに対する読み取り権限が付与されますが、API呼び出しを実行するユーザーには、アクセス対象の項目に対するアクセス権限が必要です。

つまり、JWT認証済みのアプリケーションが管理対象ユーザーの項目にアクセスする場合、アプリケーションは、その項目にアクセスできるユーザーとして認証されるようにas-userヘッダーを使用するか、ユーザーアクセストークンを作成する必要があります。

すべてのファイルとフォルダの読み取りと書き込み

OAuthスコープroot_readwrite
アプリケーションスコープBoxに格納されているすべてのファイルとフォルダの読み取りと書き込み

アプリケーションには、認証済みユーザーの書き込みアクセス権限が付与されます。これにより、アプリケーションでは、ファイルのアップロード、新しいバージョンのファイルのアップロード、新しいフォルダの作成、コラボレーションの作成、編集、削除、コメント、タスク、コレクションの作成などを実行できます。

これにより、アプリケーションには項目に対する読み取り/書き込みアクセス権限が付与されますが、API呼び出しを行うユーザーには、アクセス対象の項目に対するアクセス権限が必要です。

ユーザーを管理

開発者コンソールにある「ユーザーを管理」アプリケーションスコープオプションは、実際に2つのOAuthスコープにマップされます。

OAuthスコープmanage_managed_users
アプリケーションスコープユーザーを管理

アプリケーションには、標準(管理対象)のBoxユーザーを管理するための権限が付与されます。これにより、このアプリでは、ユーザーのプライマリログインの変更、ユーザーのパスワードのリセット、管理対象ユーザーのロールの変更を実行できます。

これにより、アプリケーションにはユーザーへのアクセス権限が付与されますが、認証済みユーザーにはこれらのユーザーへのアクセス権限が必要です。クライアント側の認証済みアプリケーションの場合は、ユーザーが管理者または共同管理者である必要があります。

つまり、JWTアプリケーションの場合は、「会社」レベルのアプリケーションアクセスが可能になるように追加でアプリケーションを構成する必要があります。

OAuthスコープmanage_app_users
アプリケーションスコープユーザーを管理

アプリケーションには、標準のApp Userを管理するための権限が付与されます。App Userは通常の(管理対象)ユーザーとは異なり、Boxウェブアプリにログインできません。代わりに、App Userは仮想ユーザーとして、アプリケーションがサーバー側の認証済みアプリケーションにデータを分離するために使用できます。

このスコープは、サーバー側で認証されている(JWT)アプリケーションのみに適用されます。

グループを管理

OAuthスコープmanage_groups
アプリケーションスコープグループを管理

アプリケーションには、会社のグループを管理するための権限が付与されます。これにより、このアプリでは、グループの作成、更新、削除のほか、グループでのユーザーの追加と削除を実行できます。

これにより、アプリケーションにはユーザーグループへのアクセス権限が付与されますが、認証済みユーザーにはこれらのユーザーへのアクセス権限が必要です。つまり、クライアント側の認証済みアプリケーションの場合は、ユーザーが管理者または共同管理者である必要があります。

つまり、JWTアプリケーションの場合は、「会社」レベルのアプリケーションアクセスが可能になるように追加でアプリケーションを構成する必要があります。

Webhookを管理

OAuthスコープmanage_webhook
アプリケーションスコープWebhookを管理

アプリケーションには、ユーザーのWebhookを作成するための権限が付与されます。Webhookにはいくつかの制限があります。注目すべきは、1ユーザーにつき1つのアプリケーションあたりWebhookは1,000個までという制限があることです。

エンタープライズのプロパティを管理

OAuthスコープmanage_enterprise_properties
アプリケーションスコープエンタープライズのプロパティを管理

アプリケーションには、エンタープライズイベントストリームを表示するための権限に加え、エンタープライズの属性とレポートを表示および編集するための権限が付与されます。さらに、アプリケーションでは、Device Pinnerの編集と削除も実行できます。

これにより、アプリケーションにはユーザーグループへのアクセス権限が付与されますが、認証済みユーザーにはこれらのユーザーへのアクセス権限が必要です。

リテンションポリシーを管理

OAuthスコープmanage_data_retention
アプリケーションスコープリテンションポリシーを管理
依存先gcmスコープ

アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、会社ではBox Governanceを購入しておく必要があります。

このスコープが適切に機能するには、gcmスコープを必要とします。このスコープは、当社のサポートチャネルでチケットを作成してリクエストできます。

リクエストに応じて使用可能

アプリケーションに対して特定の機能を有効にするリクエストで使用可能な追加のスコープがいくつかあります。

これらのスコープは、Boxのサポートチームを通じてチケットを作成することでリクエストできます。サポートチームは、個別にリクエストを確認し、ユースケースにスコープが必要な場合のみ承認を行います。

無料トライアルのアカウントでは、スコープを追加でリクエストすることはできません。以下に示すスコープの有効化についてサポートリクエストを申請する前に、有料のEnterpriseアカウントにログインするか、無料のDeveloperアカウントをEnterpriseアカウントプランにアップグレードしてください。

リーガルホールドの管理

OAuthスコープmanage_legal_holds
アプリケーションスコープリテンションポリシーを管理
依存先gcmスコープ

アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、会社ではBox Governanceを購入しておく必要があります。

このスコープが適切に機能するには、gcmスコープを必要とします。このスコープは、当社のサポートチャネルでチケットを作成してリクエストできます。

メール通知の抑制

アプリケーションスコープAPI呼び出しからメール通知を抑制可能

API呼び出しが行われるときにメール通知を抑制できます。

グローバルコンテンツマネージャ

OAuthスコープgcm
アプリケーションスコープグローバルコンテンツマネージャ

社内のコンテンツへのアクセス権限を持つユーザーとして明示的に認証されていなくても、管理者とサービスアカウントは社内のすべてのコンテンツを取得できます。このスコープは、リテンションポリシーとリーガルホールドを使用する特定のアプリケーションで必要になる場合があります。

副次的影響

アプリケーションに対してこのスコープを有効にすると、一部のAPI呼び出しの動作が変更されます。その最も顕著な例として、as-userヘッダーを使用してユーザーとして明示的に認証しないとコンテンツを書き込めなくなることが挙げられます。また、このスコープを有効にすると、別の会社のユーザーが所有するコンテンツにはアクセスできなくなります。

そのため、やむを得ない場合を除き、このスコープはプロビジョニングされません。

ダウンスコープ用のスコープ

特にトークンをクライアント側(ブラウザなどの公開された環境)に公開する必要がある場合など、アクセストークンをより厳格な権限レベルにダウンスコープしなければならないことがあります。その主な例として、ユーザーのブラウザでアクセストークンが必要となるBox UI Elementsを使用する場合が挙げられます。

既存のアクセストークンをダウンスコープするためにPOST /oauth2/tokenエンドポイントで使用できる追加のスコープのリストを以下に示します。

OAuthスコープ影響を受けるUI Element説明
annotation_editPreview注釈の編集と削除をユーザーに許可します。
annotation_view_allPreviewすべてのユーザーによる注釈の表示をユーザーに許可します。
annotation_view_selfPreviewユーザーに自分の注釈のみの表示を許可します。
base_explorerExplorerユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。
base_pickerPickerユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。
base_previewPreviewファイルのプレビューのみをユーザーに許可します。
base_sidebarSidebarサイドバーUI Elementに必要なファイルの基本情報の取得をユーザーに許可します。
base_uploadUploaderトークンのダウンスコープ時に、resourceの下で指定されたフォルダへのアップロードを許可します。
item_deleteExplorerファイルとフォルダの削除を許可します。
item_downloadExplorer、Previewファイルまたはフォルダのコンテンツのダウンロードを許可します。
item_previewExplorerファイルのプレビューを有効にします。
item_renameExplorerファイルとフォルダの名前変更を許可します。
item_shareExplorer、Pickerトークン交換のresourceで指定された項目の共有を許可します。
item_uploadPickerContent Pickerでのアップロードを許可します。

また、ダウンスコープ時には標準OAuthスコープもサポートされます。

OAuthスコープ説明
root_readonlyBoxに格納されているすべてのファイルとフォルダの読み取り
root_readwriteBoxに格納されているすべてのファイルとフォルダの読み取りと書き込み
manage_managed_users管理対象ユーザーを管理
manage_app_usersApp Userを管理
manage_groupsグループを管理
manage_webhookWebhookを管理
manage_enterprise_propertiesエンタープライズのプロパティを管理
manage_data_retentionリテンションポリシーを管理