Box Connector Configuration
The Gimmal Box Connector allows a Box admin or co-admin to configure settings via a web page. The following sections explain how to configure the Connector after it has been deployed for you.
Sign In to Box Connector
When you sign into Box Connector, you will be asked for your Box URL in order to authenticate you against your Box account. Only a user that belongs to the Box admin or co-admin role will be able to configure the connector. Box will ask for your consent to allow the connector to access your Box account.
After you have signed in to your Box account, then you will be redirected back to the connector. If your Box session expires, even if you have NOT closed your web browser, you will automatically be redirected to authenticate with Box and grant access to the Connector again.
Create a Service Account
Before continuing with configuration a Gimmal Records Management administrator will be required to create a service account for the Box Connector.
Records Management Configuration
After signing in to the connector, you should configure the Records Management Configuration section first.
- URL - This field is the URL for your Gimmal Records Management server. If you are hosting your own instance of the product, then you must ensure public inbound HTTPS traffic is allowed for it. Configuring your network firewall or router is beyond the scope of normal Gimmal support. However, Gimmal support can provide your network or security operations team with the list of IP addresses the Connector uses. If your Gimmal Records Management tenant is hosted by Gimmal, then no additional configuration is required.
- Username - This is a service account created in your Records Management instance. If your Records Management is hosted by Gimmal, then your service account Username must include your tenant domain and will resemble an email address. For example, a Gimmal hosted Records Management service account should resemble the following: box-svc@domain.com. If you are hosting your own instance of Records Management, then your service account Username does not use a tenant domain. For example, it should resemble the following: box-service.
- Password - This field represents the password for the box service account created in your Records Management instance.
Box Configuration
This screen requires you to provide the Connector with the information obtained from the topic (5.2.3) Configuring Box.
It is critical to configure the User Authentication and Server Authentication sections correctly, or you may have to contact Gimmal Support.
This section has two fields that are global for your Connector:
URL: This field is the URL to your Box account. Be sure to include your custom subdomain. For example, https://acme.app.box.com.
Enterprise ID: This field is your Box enterprise ID.
Authentication Sections
There are two separate authentication types for each of the two apps configured in your Box Account. Each authentication type requires you to configure the appropriate OAuth 2.0 credentials required to communicate with your Box apps required above in the Configuring Box section
User Authentication
Server Authentication
User Authentication
This section is pre-populated by Gimmal during your Connector deployment. It contains the client ID and client secret for the app that allows a Box admin or co-admin to manage the connector. WARNING: misconfiguring this section could cause you to be locked out of your Connector and would require opening a Gimmal support ticket in order to have it reset.
Client ID: This field is the client ID for the Box User App.
Client Secret: This field is the client secret for the Box User App.
Server Authentication
This section requires you to know the RSA keypair you configured for the Box Server-to-Server app. If you do not know them, then you will need to regenerate the keypair since Box cannot retrieve them for you.
Client ID: This field is the client ID for the Box Server-to-Server app.
Client Secret: This field is the client secret for the Box Server-to-Server app.
Public Key ID: This field is the value (do NOT include the quotation marks) of the publicKeyID element in the JSON config file for your RSA keypair.
Private Key: This field is the value (do NOT include the quotation marks) of the privateKey element in the JSON config file for your RSA keypair.
Private Key Passphrase: This field is the value (do NOT include the quotation marks) of the passphrase element in the JSON config file for your RSA keypair.
Box User Email: This user must be a member of the admin or co-admin roles in your Box account and have the “Run new reports and access existing reports” permission. The Connector uses the Box API Admin Events stream to detect changes to files in your Box account.