ユーザー権限とスコープ
アクションを実行するための適切なスコープがアプリケーションに設定されている場合でも、アクセストークンと関連付けられた、呼び出しを実行するユーザーにはそのアクションを実行するための権限が必要であり、逆の場合も同様であることを理解することが重要です。 たとえば、ファイルを読み取るようにアプリケーションが設定されている場合、アクセスしようとするファイルの読み取り権限が認証済みユーザーにも必要です。 スコープ、トークンの権限、ユーザー権限がどのように連携しているかの詳細については、Boxのを参照してください。スコープとOAuth 2承認
アプリケーションを承認するためにクライアント側のOAuth 2フローを介してユーザーを送信する際は、承認URLに一連のスコープを追加してユーザーのアクセストークンをさらに制限できます。 たとえば、アプリケーションでroot_readonlyおよびroot_readwriteスコープが有効になっている場合は、ユーザーのリダイレクト時にこのスコープを指定することで、ユーザーのアクセストークンをroot_readonlyに制限できます。
セルフサービススコープ
これらのスコープは、アプリケーションの設定時に開発者コンソールから使用できます。[構成] タブの [アプリケーションスコープ] セクションに移動して、以下のスコープから1つ以上を選択します。すべてのファイルとフォルダの読み取り
アプリケーションで、認証済みユーザーはすべてのファイル/フォルダを読み取ることができるようになります。
これにより、アプリケーションにはファイルとフォルダに対する読み取り権限が付与されますが、APIコールを実行するユーザーには、アクセス対象の項目に対するアクセス権限が必要です。
つまり、アプリケーションがの項目にアクセスする場合、サービスアカウントのトークンは、そのコンテンツにアクセスできるユーザーとして直接認証されるように、
as-userを使用するか、を作成する必要があります。
すべてのファイルとフォルダの読み取りと書き込み
アプリケーションには、認証済みユーザーの書き込みアクセス権限が付与されます。これにより、アプリケーションでは、ファイルまたは新しいファイルバージョンのアップロード、コンテンツのダウンロード、新しいフォルダの作成、コラボレーションの更新または削除、コメントまたはタスクの作成などを実行できるようになります。
これにより、アプリケーションには項目に対する読み取り/書き込みアクセス権限が付与されますが、APIコールを行うユーザーには、コンテンツに対するアクセス権限が必要です。
ユーザーを管理する
開発者コンソールにある「ユーザーを管理する」スコープは、2つのOAuthスコープにマップされます。
アプリケーションには、を管理するための権限が付与されます。これにより、このアプリでは、ユーザーのプライマリログインの変更、ユーザーのパスワードのリセット、管理対象ユーザーのロールの変更を実行できます。
これを使用すると、アプリケーションでユーザーを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。さらに、JWTアプリケーションの場合は、を [アプリアクセス + Enterpriseアクセス] にしてアプリケーションを設定する必要があります。
アプリケーションには、を管理するための権限が付与されます。つまり、このスコープは、サーバー側で認証されている (JWT) アプリケーションのみに適用されます。
グループを管理する
アプリケーションには、企業のグループを管理するための権限が付与されます。これにより、このアプリでは、グループの作成、更新、削除のほか、グループメンバーシップの管理を実行できます。
これを使用すると、アプリケーションでグループを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。さらに、JWTアプリケーションの場合は、を [アプリアクセス + Enterpriseアクセス] にしてアプリケーションを設定する必要があります。
Webhookを管理する
アプリケーションには、ユーザーのWebhookを作成するための権限が付与されます。Webhookのを確認してください。注目すべきは、1ユーザーにつき1つのアプリケーションあたりWebhookは1,000個までという制限があることです。
Enterpriseのプロパティを管理する
アプリケーションには、Enterprise Event Streamを表示するための権限に加え、Enterpriseの属性とレポートを表示および編集するための権限が付与されます。さらに、アプリケーションでは、デバイスピンの編集と削除も実行できます。
これを使用すると、アプリケーションで企業のプロパティを管理できますが、クライアント側アプリケーションの場合、使用されるアクセストークンを、適切な権限を持つ管理者または共同管理者に関連付ける必要があります。
リテンションポリシーを管理する
アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、企業ではBox Governanceを購入しておく必要があります。
署名リクエストを管理する
アプリケーションには、署名リクエストを取得、作成、キャンセル、および再送信するための権限が付与されます。
このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。これらのスコープは、有効にしたときに自動的に選択されます。さらに、企業ではSignが有効になっている必要があります。
Box AI APIを管理する
アプリケーションには、Box AI APIにリクエストを送信するための権限が付与されます。
Box Relayを管理する
アプリケーションには、ワークフローを取得し、
WORKFLOW_MANUAL_STARTタイプのフローを開始するための権限が付与されます。
このスコープでは、アプリケーションに読み取り/書き込みスコープも設定する必要があります。
リクエストに応じて使用可能
リクエスト時にのみ使用できる追加のスコープがいくつかあります。これを使用するには、Boxのサポートチームにチケットを送信してください。サポートチームは、個別にリクエストを確認し、ユースケースにスコープが必要な場合にのみ承認を行います。無料トライアルのアカウントでは、スコープを追加でリクエストすることはできません。以下に示すスコープの有効化についてサポートリクエストを申請する前に、有料のEnterpriseアカウントにログインするか、無料のDeveloperアカウントをEnterpriseアカウントプランにアップグレードしてください。
リーガルホールドを管理する
アプリケーションには、Box Governanceでリテンションポリシーを表示および作成するための権限が付与されます。そのため、会社ではBox Governanceを購入しておく必要があります。
このスコープが適切に機能するには、
enterprise_contentスコープを必要とします。このスコープは、当社のサポートチャネルでチケットを作成してリクエストできます。メール通知を抑制する
APIコールが行われるときに、一部の種類のを抑制できます。
グローバルコンテンツマネージャ (GCM)
Enterprise設定に基づいて、管理者、共同管理者、が、所有していない、またはEnterprise内でコラボレータになっていない任意のコンテンツを取得できるようにします。
リテンションポリシーとリーガルホールドを管理するには、このスコープが必要です。
副次的影響アプリケーションに対してこのスコープを有効にすると、一部のAPIコールの動作が変更されます。その最も顕著な例として、
as-userヘッダーを使用してユーザーとして明示的に認証しないとコンテンツを書き込めなくなることが挙げられます。また、このスコープを有効にすると、別の企業のユーザーが所有するコンテンツにはアクセスできなくなります。そのため、やむを得ない場合を除き、このスコープはプロビジョニングされません。ダウンスコープ用のスコープ
特にトークンをクライアント側 (ブラウザなどの公開された環境) に公開する必要がある場合など、アクセストークンをより厳格な権限レベルにしなければならないことがあります。その主な例として、ユーザーのブラウザでアクセストークンが必要となるBox UI Elementsを使用する場合が挙げられます。 既存のアクセストークンをダウンスコープするためにエンドポイントで使用できる追加のスコープのリストを以下に示します。
また、ダウンスコープ時には標準OAuthスコープもサポートされます。