Skip to main content
Skip table of contents

Box Agent Configuration


This document describes the configuration steps that are necessary to allow Discover to manage content stored in a Box repository.

Section One – User Creation

Verify the Box edition

The Discover Box Agent supports following versions: Business, Business Plus, or Enterprise. To validate that you have one of these editions, please login to the Box Admin site using the following link:

After logging in, verify that you are using one of the supported Box editions, that information can be found on the screen shown below:

Next, click on the 'Users & Groups' option in the left-hand navigation pane, then click the button labeled '+ Users':

Fill out the highlighted sections in 'Edit User Account Details' and 'Edit User Access Permissions' as shown below (at a minimum):

Click the Save button.

Log back into the Box using the new account you just created then click on the profile icon found in the upper right-hand corner:

Click the down arrow and then click on 'Account Settings'. Scroll down to 'Authentication', check the box beside 'Require 2-step verification', enter a cell phone number, and verify the code sent via text message. Click 'Save Changes' once complete.

Section Two – Creating the Box App

Before Discover can manage information stored in the Box environment, it must be registered as an app in the Box developer portal. Creating the app allows you to specify the permissions that Discover requires and generates the security information that must be supplied when installing the Discover Box Agent.

Access the Box developer portal using the following link:

Click the 'Go to Dev Console' button and use the login credentials from Section One to access the site:

After logging in, click on the 'Create New App' tile:

Select the 'Custom App' tile and then click 'Next':

Choose the 'OAuth 2.0 with JWT' server authentication method then click 'Next':

Enter a name for the new Box app (we recommend something related to Discover) then click the 'Create App' button:

Box will verify that your new app has been created. On this verification screen, click the 'View Your App' button

Once on the app configuration page; select the 'General' option in the left-hand navigation pane, then apply the settings detailed below:

In the App Authorization section - Click on the 'Review and Submit' button.

Review App Authorization Submission – add a description of the App being requested and then click the 'Submit' button. This will email the Admin account an approval link required to activate the app.

Next, click on the 'Configuration' link in the left-hand navigation pane. Then scroll down to the following sections:

Application Access:

Click the 'Enterprise' radio button

Application Scopes:

Click ALL checkboxes

Advanced Features:

Enable both options

Add and Manage Public Keys:

Click the 'Generate a Public/Private Keypair', this will send a 2-step verification code to the cell phone number provided in section one (also a JSON file will be downloaded to the local machine)

CORS Domains:

Enter 'http://localhost:3333' into the text field

Click the 'Save Changes' button found in the upper right-hand corner to save these configuration settings.

Section Three – Editing the JSON file

The information contained in the JSON file that is created by the Box administration site must be edited before it can be linked to the appropriate Discover Agent settings. This process involves extracting various configuration settings (items a-g shown in the list below) then editing the private key to remove specific text. Gimmal strongly recommends working with one of our support team members in order to make sure these editing steps are performed correctly.

  1. Open the JSON file downloaded to the local machine in a text editor (i.e. Notepad ++). Separate the information shown below ('Box Agent settings' = 'JSON file fields'). The Box Agent settings will be supplied when you are ready to install the Agent in the Discover console

  2. ClientId = clientID

  3. ClientSecret = clientSecret

  4. JWTCertFile = privateKey (PEM file)

  5. JWTCertPassword = passphrase

  6. JWTCertSubject = "*"

  7. JWTSubject = enterpriseID

  8. JWTPublicKeyId = publicKeyID

Create a PEM file from the JSON file. The information will need to be cleaned up before the PEM file can be saved; copy/paste the 'privateKey' section into a text document. In the body of the certificate data, all instances of the character string '\n' need to be removed from the private key string.

----BEGIN ENCRYPTED PRIVATE KEY---\nMIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI+HZLbIleYm4CAggA\nMBQGCCqGSIb3DQMHBAivRxWH8LmEXwSCBMgwTcudVk5p7MsFZFbNsQsxR5loj0a4\n8Z7r6XLCVLeRWK3JG3O+d6SSYRG+EaGSc/MTPLXncEviUdmEtEwogRszzNdo88F7\nisepjlwpLJLXmvEwfTIK51wG088hPfPd9PbOAw6+sqNBpO4Y8WFwS5RZY+5DiI6F\nf04Yw1Zvy+VG5F3h49yTjA8+plWs3cU3yJtPSLMkN97bzIR0thhBYrk4pMg+nJvp\nbmu3wO4cFfaoWxMet9FaVYqX/nL4eKaiQ5Y6my0JG5rmqaNcc9f6BlNUgaHnZ8OB\nEGuQy/OsyV3LRX4HRbzqobPxlNglSeNFKWuPdP5V/V44cpVres4WWrQ2wiZFP+CC\nCmrjZg80NJ1PmLeHiNR8x0xG+W36bUAZVlbaW2GMDnLgbNGekyuT1Tzer31aP2XX\ncC8mOevPGPUBu7V5+AhYZARzG9w16F5BtRX+DkfmfCRE86DAz2iXvrpDSZE+jNSL\nCmKV18xpShVSY7uSS9jyZcexmryu8Ba77bhTnccwILXqqS8BYw4Nu8wtI2Qa+I68\nWHZutW3mTYLEdhPVOWOWkq3VrOx3gdIFtwMR4oVrqYT2/wtZ4ksP9hvyHhcxAyDX\n403IjZpZOmM29BzGYO6hh7ZnCKcN4ak7XGOI/AW3eBtLITTWzozG50hV13HcHYLA\n3ZObddaMvTkyMr0DWqgCCKZZjFahCsHXqFut7EdEHbgEdMW0Az417tUYEB5/en9a\nohdBxWmIAUINpioSejAPb8VVSmbC3lQ5BZBTRFROp6qY3FqS0UklYCMVlzCWv9uQ\n8fT/dSrfNMt9RT380/+VACHDjeAEQG9VLxBGVhqDuHSjAUiH/beUxwDXrrg6xbIl\n1AixiXMjozYyZ3kEHYEK/+Ar34GLiob6qEJHfmmeSGGNkJhYBoAcp6MZ7kdlfx+W\nUqxuOKcfuQjb79Ku94Zw+AzY97Ru7hiaK4AWyiYBzPWEgdbf5abQ/187qQZy3Z5Q\nSN7NUd1Om1UZMBnG/bRR93wD2jSpTkgZduJoN3tgSEJRcP4nmRBjY1C31AnZqeOb\nOuAuEZHFLgkzkYCtzclwghKkiPapaXzo8yHm3YEktpi6sYONQo2EinBSE50QCJg7\nqk1Jnkr3FfuWCwuPRwJQyDte4pE3E4GY0bZTl/kvNRbnljidBY4kaoHpfh7zjMWv\nKYGW42weOqxzyO+5b22y/OiJCA+uuhW21N7Tp6oEwCJK4G/5jNi31LTJvjlhTCY/\nrUpE70HFTn6sYFYuqmPg1OSupjMD0wZUtbig+9KBB6UiKlhZzKrFAfmulxgEcO10\n0YOfGBAVHHbCVHuccm61pUpAn8565OsvsGJa/yOKLr3YjwshDcPJs7PRxwAXUVS8\nNJqcLJ3q+ahV42xEDsRIa4XVRmHYJGVldQmlDpd9y38Faym0FtINV9GWTRySUZ5q\n2pmvoaj65IcqXGsUw0jEUgP8xHFrMlKpNgq/a0BBEeGMv5JHanRaTyJXo3D+u0Uf\n02u1JI1LZQwM1RdYQKYD3aE37gsOfPStQrs8eFis/AMYZRifMTrxUY/CoElX8skj\ntr7YJBdQ/eCXog2Agu1oiBo6wMyyCORG47owF7NqT/gNZ9BVQXNGETpHwB1rPurt\npzw=\n---END ENCRYPTED PRIVATE KEY----\n",

Once the file is in the proper format, save the file as a text document. Then rename the extension of the file you just saved to .PEM and store it in a secure location on the Connector machine.

Section Four – Installing the Discover Box Agent


NOTE: Install the Box Agent through the Add Agent List option in the Agents List page of Discover console (outlined below). You may also install the Box Agent when initially installing the Connector and Agents using the Connector Setup program downloaded from the Download Center of the Discover console.

Discover Box Agent Installation:

The Box Agent for Discover can be installed from the web dashboard by following the steps outlined below.

  1. Go to the 'Administration' tab on the top of the dashboard. In the left hand navigation pane click on 'Configuration' then 'Connectors'.

    • Choose the connector device by checking the appropriate box.

    • Click on the orange More button and choose 'Agent List'.

Click on the green Action button then select 'Add Agent'.

Select the 'Box Agent Service'.

Next click on the 'Box Settings' tab; fill out the corresponding fields that match the Box Settings file generated in Section Three. Click 'Add' when finished.

There are two ways to speed up the installation of the agent. On the Connector server either:

  • Shutdown and restart the Gimmal Connector service, or

  • Open the Gimmal Connector Status Tool and click the 'phone home' button shown below

After the Box Agent service has been installed, proceed with adding a Data Target search for Data Owners (using the Box Accounts option) and for Box File Paths. For more information on building Data Target searches, please refer to this Searching for Data Targets

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.