Box Agent Configuration
Introduction:
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.
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
ClientId = clientID
ClientSecret = clientSecret
JWTCertFile = privateKey (PEM file)
JWTCertPassword = passphrase
JWTCertSubject = "*"
JWTSubject = enterpriseID
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.
BEFORE:
----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",
AFTER:
----BEGIN ENCRYPTED PRIVATE KEY----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI+HZLbIleYm4CAggA
MBQGCCqGSIb3DQMHBAivRxWH8LmEXwSCBMgwTcudVk5p7MsFZFbNsQsxR5loj0a4
8Z7r6XLCVLeRWK3JG3O+d6SSYRG+EaGSc/MTPLXncEviUdmEtEwogRszzNdo88F7
isepjlwpLJLXmvEwfTIK51wG088hPfPd9PbOAw6+sqNBpO4Y8WFwS5RZY+5DiI6F
f04Yw1Zvy+VG5F3h49yTjA8+plWs3cU3yJtPSLMkN97bzIR0thhBYrk4pMg+nJvp
bmu3wO4cFfaoWxMet9FaVYqX/nL4eKaiQ5Y6my0JG5rmqaNcc9f6BlNUgaHnZ8OB
EGuQy/OsyV3LRX4HRbzqobPxlNglSeNFKWuPdP5V/V44cpVres4WWrQ2wiZFP+CC
CmrjZg80NJ1PmLeHiNR8x0xG+W36bUAZVlbaW2GMDnLgbNGekyuT1Tzer31aP2XX
cC8mOevPGPUBu7V5+AhYZARzG9w16F5BtRX+DkfmfCRE86DAz2iXvrpDSZE+jNSL
CmKV18xpShVSY7uSS9jyZcexmryu8Ba77bhTnccwILXqqS8BYw4Nu8wtI2Qa+I68
WHZutW3mTYLEdhPVOWOWkq3VrOx3gdIFtwMR4oVrqYT2/wtZ4ksP9hvyHhcxAyDX
403IjZpZOmM29BzGYO6hh7ZnCKcN4ak7XGOI/AW3eBtLITTWzozG50hV13HcHYLA
3ZObddaMvTkyMr0DWqgCCKZZjFahCsHXqFut7EdEHbgEdMW0Az417tUYEB5/en9a
ohdBxWmIAUINpioSejAPb8VVSmbC3lQ5BZBTRFROp6qY3FqS0UklYCMVlzCWv9uQ
8fT/dSrfNMt9RT380/+VACHDjeAEQG9VLxBGVhqDuHSjAUiH/beUxwDXrrg6xbIl
1AixiXMjozYyZ3kEHYEK/+Ar34GLiob6qEJHfmmeSGGNkJhYBoAcp6MZ7kdlfx+W
UqxuOKcfuQjb79Ku94Zw+AzY97Ru7hiaK4AWyiYBzPWEgdbf5abQ/187qQZy3Z5Q
SN7NUd1Om1UZMBnG/bRR93wD2jSpTkgZduJoN3tgSEJRcP4nmRBjY1C31AnZqeOb
OuAuEZHFLgkzkYCtzclwghKkiPapaXzo8yHm3YEktpi6sYONQo2EinBSE50QCJg7
qk1Jnkr3FfuWCwuPRwJQyDte4pE3E4GY0bZTl/kvNRbnljidBY4kaoHpfh7zjMWv
KYGW42weOqxzyO+5b22y/OiJCA+uuhW21N7Tp6oEwCJK4G/5jNi31LTJvjlhTCY/
rUpE70HFTn6sYFYuqmPg1OSupjMD0wZUtbig+9KBB6UiKlhZzKrFAfmulxgEcO10
0YOfGBAVHHbCVHuccm61pUpAn8565OsvsGJa/yOKLr3YjwshDcPJs7PRxwAXUVS8
NJqcLJ3q+ahV42xEDsRIa4XVRmHYJGVldQmlDpd9y38Faym0FtINV9GWTRySUZ5q
2pmvoaj65IcqXGsUw0jEUgP8xHFrMlKpNgq/a0BBEeGMv5JHanRaTyJXo3D+u0Uf
02u1JI1LZQwM1RdYQKYD3aE37gsOfPStQrs8eFis/AMYZRifMTrxUY/CoElX8skj
tr7YJBdQ/eCXog2Agu1oiBo6wMyyCORG47owF7NqT/gNZ9BVQXNGETpHwB1rPurt
pzw=
----END ENCRYPTED PRIVATE KEY----
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.
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