Configuring Box

The following sections explain the required information, settings, and apps needed in your Box account before you can start using the Connector.

Box Enterprise ID

Your enterprise ID is available in several places throughout Box. You can easily find it within the Admin Console under the Account & Billing page.

Custom Subdomain

You must configure your box account to use a custom subdomain. This enables the Gimmal Box Connector to uniquely identify requests to/from your Box account back to your Gimmal Box Connector subscription. For more details, please follow Box’s instructions on their Custom Setup for your Enterprise page.

• Sign in to your Box Account.

• Access your admin console.

• Navigate to the Custom Setup tab.

• Under the Custom Subdomain section, ensure you have entered a value and click Save.

Box App

You are required to create two Box Custom Apps in order for the connector to communicate with your Box account—both a Box User App and a Box Server-to-Server App. Please note that the majority of this information comes from Box’s documentation. For more details beyond what is provided by Gimmal, please see Box’s Creating Your First Application page.

Box User App

This is a standard OAuth 2.0 app in Box (which Box also refers to as User Authentication). For more details, please see Box’s Setup with OAuth 2.0 developer page. This app allows you to manage the connector through a web browser.

1. Create a new Custom App Box app that uses the User Authentication (OAuth 2.0) authentication method.
   

   

2. Configure the app:

   1. Redirect URI – This will be the URI of the server where the Box Connector will be installed. You will need to supply the URI by itself, the URI with /sign-in appended to the end, and the URI with /signin-box appended to the end. Below is an example of how that should look:

      

      Application Scopes - Select all of the following:

      1. Read all files and folders stored in Box.

      2. Write all files and folders stored in Box.

      3. If your organization is using Box Governance, also select Manage Retention Policies.
         

         

   2. CORS Domains – This should be the same set of URIs supplied for the Redirect URIs section.
      
      (Note: these URIs are comma-separated.)

      

   3. Click Save Changes.

Box Server-to-Server App

This is an OAuth 2.0 with JWT app in Box (which Box also refers to as Server Authentication). For more details, please see Box’s Setup with JWT developer page. This app enables the connector to communicate with your Box account as a background service without any user interaction.

1. Create a new Custom App that uses the Server Authentication (with JWT) authentication method.
   

   

2. Configure the app:

   1. Application Access is Enterprise.
      

      

   2. Application Scopes - Select all of the following:

      1. Read all files and folders stored in Box.

      2. Write all files and folders stored in Box.

      3. Manage users.

      4. Manage enterprise properties.

      5. If your organization is using Box Governance, also select Manage Retention Policies.
         

         

   3. Advanced Features:

      1. Make API calls using the as-user header is enabled.

      2. Generate user access tokens is enabled.
         

         

3. Generate a Public/Private Keypair by following the instructions in Box's documentation (please note that this requires Multi-factor Authentication be enabled on your Box account).
   

   

4. CORS Domains – This should be the same set of URIs used for the OAuth 2.0 User App that was configured earlier.
   (Note: these URIs are comma-separated.)

   

5. Click Save Changes.

6. Authorize and Approve the app. For full details, please see Box's documentation for Authorizing Custom Applications in Sandbox and Production Environments.

   1. Under the Authorize tab, click the Review and Submit button.

      

      The authorization status will be Pending Authorization. This must be reviewed by an Administrator on the Box account.

      

   2. Go to the Admin Console on the Box account and navigate to the Apps tab.

   3. Click on Custom Apps Manager at the top of the page.

   4. The Server Authentication (with JWT) app you created should be present. Click the ellipsis (…) next to the app and select Authorize App from the drop down menu.

      

      Once done, the app should say Authorized and Enabled.