開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーに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を使用する場合が挙げられます。
既存のアクセストークンをダウンスコープするためにエンドポイントで使用できる追加のスコープのリストを以下に示します。
| 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 | アップローダー | トークンのダウンスコープ時に、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 | 署名リクエストを管理する |
