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
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:
- A plain-text editor, such as Windows Notepad
- Two-factor authentication (2FA) enabled in Box
Step 1. Create a custom Box application
- From Dev Console in Box, click Create New App.
- Select Custom App, and click Next.
- Under Authentication Method, select OAuth 2.0 with JWT, and click Next.
- 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
- From Dev Console in Box, select Configuration for the custom app.
- Under Authentication Method, verify OAuth 2.0 with JWT is selected.
- Under Application Access, select Enterprise, and click Save Changes.
- In a plain-text editor, open the
public.pemfile, and copy its entire contents, including the header line
-----BEGIN PUBLIC KEY-----, footer line
-----END PUBLIC KEY-----, and any trailing spaces.
- From Dev Console in Box, select Configuration for the custom app, and click Add a Public Key under Add and Manage Public Keys.
- Paste the entire contents from the
public.pemfile, and click Verify and Save.
- When prompted, enter the 2FA code for your Box account, and click Submit.
- Under OAuth 2.0 Credentials, copy the custom app's client ID.
Step 4. Authorize the custom app in Box
- From Admin Console in Box, click Apps.
- On the Custom Apps tab, click Authorize New App.
- Paste the custom app's client ID, and click Next.
- Under App Authorization, verify the app is authorized for All Users, and click Authorize.
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.
- From Chain Builder, click Connections , and then Create at the top right.
- Under BizApp Connection, select Box and the default CloudRunner.
- Under Basic Info, enter a unique name and description to help identify the connection.
- 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.pemfile 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.
- Select the environments to use the connection, and click Save.
- To test the connection, create and run a chain with the connector's Get Folder Info command, and verify it returns a valid output.
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
private.pemfiles 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.