Box Developerドキュメント
 

    スコープ

    スコープ

    開発者コンソールでアプリケーションが作成されると、ユーザーはアプリケーションのスコープを設定する必要があります。ユーザーに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に格納されているすべてのファイルとフォルダの読み取り

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

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

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

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

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

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

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

    ユーザーを管理する

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

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

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

    これを使用すると、アプリケーションでユーザーを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。

    さらに、JWTアプリケーションの場合は、アプリケーションアクセスを [アプリアクセス + Enterpriseアクセス] にしてアプリケーションを設定する必要があります。

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

    アプリケーションには、App Userを管理するための権限が付与されます。つまり、このスコープは、サーバー側で認証されている (JWT) アプリケーションのみに適用されます。

    グループを管理する

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

    アプリケーションには、企業のグループを管理するための権限が付与されます。これにより、このアプリでは、グループの作成、更新、削除のほか、グループメンバーシップの管理を実行できます。

    これを使用すると、アプリケーションでグループを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。

    さらに、JWTアプリケーションの場合は、アプリケーションアクセスを [アプリアクセス + Enterpriseアクセス] にしてアプリケーションを設定する必要があります。

    Webhookを管理する

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

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

    Enterpriseのプロパティを管理する

    OAuthスコープmanage_enterprise_properties
    アプリケーションスコープEnterpriseのプロパティを管理する

    アプリケーションには、Enterprise Event Streamを表示するための権限に加え、Enterpriseの属性とレポートを表示および編集するための権限が付与されます。さらに、アプリケーションでは、デバイスピンの編集と削除も実行できます。

    これを使用すると、アプリケーションで企業のプロパティを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。

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

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

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

    このスコープを使用するには、enterprise_contentスコープも適切に機能する必要があります。これらのスコープをリクエストするには、当社のサポートチャネルでチケットを作成します。

    署名リクエストを管理する

    OAuthスコープsign_requests.readwrite
    アプリケーションスコープ署名リクエストを管理する

    アプリケーションには、署名リクエストを取得、作成、キャンセル、および再送信するための権限が付与されます。

    このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。これらのスコープは、有効にしたときに自動的に選択されます。さらに、企業ではSignが有効になっている必要があります。

    Box AI APIを管理する

    OAuthスコープAI.readwrite
    アプリケーションスコープAIを管理する

    アプリケーションには、Box AI APIにリクエストを送信するための権限が付与されます。

    Box Relayを管理する

    OAuthスコープmanage_triggers
    アプリケーションスコープBox Relayを管理する

    アプリケーションには、ワークフローを取得し、WORKFLOW_MANUAL_STARTタイプのフローを開始するための権限が付与されます。

    このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。

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

    リクエスト時にのみ使用できる追加のスコープがいくつかあります。これを使用するには、Boxのサポートチームにチケットを送信してください。サポートチームは、個別にリクエストを確認し、ユースケースにスコープが必要な場合にのみ承認を行います。

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

    リーガルホールドを管理する

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

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

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

    メール通知を抑制する

    アプリケーションスコープAPIコールからメール通知を抑制する

    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_explorerExplorerユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。
    base_pickerPickerユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。
    base_previewプレビューファイルのプレビューのみをユーザーに許可します。
    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_propertiesEnterpriseのプロパティを管理する
    manage_data_retentionリテンションポリシーを管理する
    sign_requests.readwrite署名リクエストを管理する