Workiva Support Center

With the Box® connector, you can use commands to interact with Box drives, such as to:

• Search and manage files
• Create and delete folders
• Retrieve URLs for files and folders

Note: This connector is built by Workiva and connects to a third-party system. While our Support team can help configure this connector within your workspace, we are unable to troubleshoot or otherwise assist with any issues that originate outside of the Workiva platform.

Prerequisites

To set up the connector, you'll need:

• A custom Box app for the service account integration
• The custom app's enterprise ID, client ID and secret, and private key

Create a service account integration in Box

Before you set up the Box connector, create a custom Box app for the service account integration. To configure the app's public/private key pair, you'll need: 

• OpenSSL
• A plain-text editor, such as Windows Notepad
• Two-factor authentication (2FA) enabled in Box

Step 1: Create a custom Box application

1. From Dev Console in Box, click Create New App.
2. Select Custom App, and click Next.
   
3. Under Authentication Method, select OAuth 2.0 with JWT, and click Next.
   
4. Enter a unique name to help identify the app, such as Workiva Box App, and click Create App and then View Your App.
   

Step 2: Create the app's RSA key pair

To secure the connection, the Box connector authenticates using the custom app's Rivest-Shamir-Adleman (RSA) public/private key pair. To create this key pair in OpenSSL, enter these commands:

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

These commands generate two files:

• private.pem, which contains the client key the connector uses to authenticate with Box
• public.pem, which the custom app requires for its configuration

Step 3: Configure the custom app

1. From Dev Console in Box, select Configuration for the custom app.
2. Under Authentication Method, verify OAuth 2.0 with JWT is selected.
   
3. Under Application Access, select Enterprise, and click Save Changes.
   
4. In a plain-text editor, open the public.pem file, and copy its entire contents, including the header line -----BEGIN PUBLIC KEY-----, footer line -----END PUBLIC KEY-----, and any trailing spaces.
5. From Dev Console in Box, select Configuration for the custom app, and click Add a Public Key under Add and Manage Public Keys.
   
   
6. Paste the entire contents from the public.pem file, and click Verify and Save.
7. When prompted, enter the 2FA code for your Box account, and click Submit.
8. Under OAuth 2.0 Credentials, copy the custom app's client ID.
   

Step 4: Authorize the custom app in Box

1. From Admin Console in Box, click Apps.
2. On the Custom Apps tab, click Authorize New App.
3. Paste the custom app's client ID, and click Next.
4. Under App Authorization, verify the app is authorized for All Users, and click Authorize.

Step 5: Add the service account id as a collaborator to a Box folder

1. From Dev Console in Box, select Configuration for the custom app.
2. Copy the service accound id.
3. Go to the Box folder that will be shared. Under Sharing, look for the Collaborators section and click Invite People to add the service account id.
   

Set up the Box connector

Note: To make the connector available for use in your organization's chains, an org security administrator first enables it from Configuration.

1. From Chain Builder, click Connections  compare_arrows, and then Create at the top right.
2. Under Connector Connection, select Box and the default CloudRunner.
   
3. Under Basic Info, enter a unique name and description to help identify the connection.
4. Under Properties, enter the connection's details:
   
   

   Property	Details
   Client ID	Enter the client ID of the custom Box app to use as the connector's service account integration. Note: From Dev Console in Box, the client ID appears under OAuth 2.0 Credentials on the custom app's Configuration tab.
   Client secret	Enter the custom app's client secret.  Note: From Dev Console in Box, the client secret appears under OAuth 2.0 Credentials on the custom app's Configuration tab.
   Client key	Enter the entire contents of the private.pem file created for the custom app, including the header line -----BEGIN RSA PRIVATE KEY-----, the footer line -----END RSA PRIVATE KEY-----, and any trailing spaces.
   Enterprise ID	Enter the custom app's enterprise ID. Note: From Dev Console in Box, the enterprise ID appears under App Info on the custom app's General tab.

   Note: All sensitive credentials are automatically encrypted and stored at Advanced Encryption Standard (AES)-256 encryption.

5. Select the environments to use the connection, and click Save.
6. To test the connection, create and run a chain with the connector's Get Folder Info command, and verify it returns a valid output.

Troubleshooting

If the connection to Box fails:

• Ensure the custom app is authorized in Box.
• Verify the custom app's client ID and secret entered for the connector. From Dev Console in Box, the client ID and secret appear under OAuth 2.0 Credentials on the custom app's Configuration tab. To reset the credentials, click Reset. 
• Ensure the entire contents of the custom app's public.pem and private.pem files are entered in the configurations of the app and connector, respectively. Include the header line, footer line, and any trailing spaces. If necessary, create a new public/private key pair in OpenSSL, and enter their contents in the configurations of the app and connector.
• Verify the custom app's enterprise ID entered for the connector. From Dev Console in Box, the enterprise ID appears under App Info on the custom app's General tab.
• Verify the folder being shared has the service account ID added as a collaborator.