The purpose of this article is to guide Box Administrators on how to safely allow access to their Box enterprise and user content from custom built applications using Box's API. Some applications have the potential to be harmful if used incorrectly, so it's important to be mindful of the following information when whitelisting or authorizing applications.
Some common scenarios that this article addresses are:
- Admins receiving requests from users to authorize or whitelist a custom built application (using a "Client ID" or "API Key") from a user/developer.
- Admins beginning to lead their own projects, building on Box's API, seeking a better understanding of how to evaluate application scopes.
Whitelisting an Application
If an administrator receives a request to whitelist an application, the following prerequisite is assumed:
- The administrator has enabled "Block unpublished apps by default" per Restricting Applications from the Admin Console - hence, the need for a whitelist.
The administrator should:
- Log in to the application (your screen will look like the screenshot below) and review the scopes at the Grant Access page. For more information on reviewing scopes, please see the below section on Reviewing Scopes.
- Document the change to whitelist the application's Client ID (API Key), including the time, date, admin who performed the action, application owner, application name, and application purpose.
Screenshot of a typical custom integration's log in page:
Authorizing an Application
If an administrator receives a request to authorize an application, the administrator should:
- Follow the steps in Enabling Custom Built Applications.
- At step 5, review the scopes (see below) and decide whether or not to allow the application, based on the scopes.
- If the application is unpublished, add the application's Client ID to the whitelist (see above section on Whitelisting an Application).
Most scopes are self explanatory (e.g. Manage Users, Read and Write files and folders, etc...). An important thing to note is how the application's scopes (essentially application permissions) interact with user permissions.
Example Scenario 1
- Application has access to "read and write" files
- User permission is "Viewer"
- If the user tries to delete a file under the folder (where the user is a Viewer) through the application, then the call will fail with a permissions error
Example Scenario 2
- Application only has access to "read and write" files
- User is the primary admin
- If the user tries to run reports through the application, then the call will fail with a permissions error
Example Scenario 3
- Application has access to "Manage Users"
- User is a co-admin with "Manage Users" permission
- If the user attempts to rename a user, the call will succeed
The scopes above should raise red flags. "Read and write all files and folders stored in Box" alone doesn't automatically mean that the application can read and write all files and folders. The "for the following users" setting does say "All users", but if the "For the following users" setting was to "Application Only", then this application would only be able to access content under its app users (and not managed users in the rest of the enterprise)!
Additionally, this application can generate tokens for any user - including the admin.
The scopes above should also raise red flags. This application can not only read/write files and folders, but also manage nearly everything in the enterprise (delete/create users, delete/create retention policies, legal hold policies, and impersonate users).
If you would like to learn more about scopes please visit our developer documentation by clicking here.
If the administrator has any questions, the responsibility of justifying the requested scopes falls to the developer of the application. While Box can clarify what a particular scope means, Box has no knowledge of the use case or code behind an application.