Custom Apps Manager Updates
Today, we released updates to the custom application management process in the Box Admin Console. The goal of this article is to prepare you to handle requests to authorize or enable custom applications for use within your Box enterprise, as well as learn about the updates that were released. By the end, you should have a basic understanding of:
- Authentication
- Authorization
- Access tokens
- Application Scopes
Before diving in, it is critical to understand the difference between authentication and authorization. Authentication is the validation that a user is who they say they are. For example, you authenticate using a username and password when you login to Box. After authenticating, authorization occurs when you try to access resources. This is the validation that you have permission to access the requested content.
Box supports four different industry standard types of authentication via the API: Standard OAuth 2.0, Server Authentication with JWT, Server Authentication with Client Credentials Grant, and App Token Authentication.
Each authentication type provides a different secure way of achieving the same goal: obtaining an access token. Access tokens can be thought of as a key developers use to make API calls.
- Standard OAuth 2.0 uses Box to identify users. This means that when a user wants to access an application they are redirected to the Box login screen to input their username and password. If successful, they can grant the application access to take actions on their behalf.
- Server Authentication with JWT and Client Credentials Grant rely on developers to use their own identity management system. Applications using these two authentication types automatically generate a Service Account, which can be thought of as an “App Admin”. With the right scopes enabled, a Service Account can perform many Admin actions, thus always requiring Admin authorization, or approval, before use.
- App Token Authentication is a subset of JWT and only provides access to a small subset of API functionality. This app type is only to be selected for preview use cases leveraging Box View.
When reviewing an application for approval, you’ll need to review the requested app scopes. These can look scary at first, because you do not want to grant too much access. However, as a general rule of thumb, the API abides by the same restrictions as the web application. This means that if the user cannot perform the action via the web application, they will not be able to via the API.
Application scopes determine what API endpoints an application is able to interact with successfully. For example, if the ‘manage users’ scope is not selected, the application will not be able to successfully make API calls related to managing users.
Because scopes work in conjunction with user permissions, granting the “write all files and folders stored in Box” scope does not automatically provide a user with API access to all content in a Box enterprise. Instead, it means that the authenticated user can receive successful API responses when making write calls to content they either own or are collaborating on and have a high enough permission level to edit.
Below is a look at the options developers are given in the Developer Console.
JWT, App Token, or Client Credentials Example
Developers can use the automated process for JWT, App Token, or Client Credentials applications. After they have submitted their application for authorization, the primary Box admin will receive an email like this:
Upon clicking the Review App button, you are brought to the Apps tab of the Admin Console to either authorize or decline the application to take action in your enterprise.
If granted access, Access Tokens obtained for this application will be able to:
- read content
- write content
- manage users
- manage groups
- manage app users
Again, the access the user associated with the token has in the webapp comes into play. If this user is not an admin or co-admin with permission to manage users or groups, they will receive an error despite the application having this scope.
Once an application has been authorized, it will appear in the Custom Apps Manager section of the Admin Console alongside any other applications created or authorized for your Box instance.
You can also follow the manual authorization flow by clicking Add App in the top right corner. Simply type the client_id of the application in the pop-up window.
An important thing to remember is that anytime changes are made to an application’s settings in the developer console, the application must be reauthorized by the Box administrator for those changes to take effect. Steps for that process are found here.
OAuth 2.0 Example
Starting today, you will also be able to manage and view user authentication or Standard OAuth 2.0 applications.
By default, all users in your Box enterprise are allowed to enable their own OAuth 2.0 applications without administrator approval. This is allowed, because an application can only interact with content in the same way that the user can interact with content in the web application.
As an administrator, you can choose to disable unpublished applications by default. To do this, find the Settings button in the top right corner of the Customer Apps Manager screen. If you toggle the second option to on, all unpublished OAuth 2.0 applications will need administrator enablement, and server authenticated apps will require both administrator authorization and enablement.
We are currently working on implementing the same automated process as the other application types, but until that is released, applications will need to be approved manually.
In the Apps tab of the Admin Console, click Custom Apps Manager > User Authentication Apps > Add App.
A developer will need to send you the Client ID of the application they created in the Developer Console. Enter the Client ID into the text box and click Next. The enabled application will now appear in your User Authentication Apps list. You can choose to disable the application in the future from the same list.
Further reading: https://developer.box.com/guides/security/
