Box

With the Box integration, you can manage access to your Box enterprise from Opal:

• Allow users to request just-in-time access to a Box folder, at the exact collaboration role they need, from the web and Slack
• Manage Box group membership, and which folders each group can access
• Grant and revoke the Box co-admin role
• Set the right resource owners to delegate approvals to those with the most context
• Automatically revoke access when a time-bound grant expires

Opal connects as your Box enterprise’s service account, through a Box Platform App that uses Client Credentials Grant. Opal only sees the folders you share with that service account.

​

Supported resources

Opal syncs every active managed user in your Box enterprise. The integration doesn’t create or delete Box users, which arrive through SSO or your identity provider, and it doesn’t sync files or external collaborators.

​

How Box access maps to Opal

• Enterprise roles: your Box enterprise appears in Opal with the access levels User, Co-admin, and Admin. Opal can grant and revoke Co-admin, and revoking it returns the user to User. Only the Box Admin Console can change the primary Admin, so Opal syncs it, but Box rejects a grant of it from Opal.
• Folder access levels: each Box collaboration role is an access level: Previewer, Uploader, Previewer Uploader, Viewer, Viewer Uploader, Editor, and Co-owner. Owner is also listed, but Box only transfers folder ownership in Box itself, so it rejects a grant of Owner from Opal. A folder’s owner doesn’t appear among its users in Opal.
• One role per folder: Box allows each user or group one collaboration per folder. Requesting a different role on a folder changes the existing collaboration rather than adding a second one. When that grant is revoked or expires, the user returns to the role they still hold on the folder in Opal, and the collaboration is removed only if they hold no other role.
• Subfolders: Opal syncs the whole tree under each shared folder. Access in Box flows down to every subfolder, so a subfolder shows its parents’ collaborators as indirect access. To remove it, revoke it on the folder where it was granted. Box doesn’t allow a different role on a subfolder the user already accesses through a parent, so request the role on the parent instead.
• Access from outside the shared folder: if a shared folder sits inside a parent the service account can’t see, collaborators on that parent are synced as inherited. Revoking this access in Opal doesn’t remove it from Box; remove it on the parent folder in Box.
• Groups: Box group admins sync as group members. If your identity provider manages a group in Box, it may undo membership changes on its next sync.
• Notifications: Opal turns off Box’s own invitation email when it grants folder access, because Opal already notifies the requester.

​

Requirements

Before you begin, you must:

• Be an Opal Admin
• Have a Box admin who can authorize a Platform App for your enterprise
• Have the owner of each folder Opal should manage, or a Box admin, available to share it with the service account
• Ask the Opal team to enable the Box integration for your organization

​

Configuration steps

​

1. Create a Box Platform App

1. In the Box Developer Console, select New App.
2. Name the app, for example Opal, choose the Server app type, and select Create.

​

2. Configure the app

On the app’s Configuration tab:

1. Under Server Authentication Method, select Client Credentials.
2. Under App Access Level, select App + Enterprise Access.

3. Under Application Scopes, enable the following scopes, then select Save:

Opal doesn’t need the Make API calls using the as-user header or Generate user access tokens options, and never uses them.

​

3. Authorize the app

A Box admin must authorize the app before it can call the Box API. In the Admin Console, go to Integrations > Platform Apps Manager and authorize the app by its Client ID. On a Box free developer account, the app is authorized automatically. The app’s App Details panel shows Authorized once this is done.

​

4. Collect the app’s credentials

Record the following values. You’ll enter them in Opal in step 6.

​

5. Share folders with the service account

Opal manages access only to the folders shared with the app’s service account. For each top-level folder you want users to request, open Share in Box, invite the service account login from step 4, set the role to Co-owner, and select Send. Opal syncs every subfolder under a shared folder, so you don’t need to share subfolders separately.

​

6. Create the Box app in Opal

In Opal, go to Inventory > +App and select Box. Fill in the following fields: Opal checks the credentials when you save the app.

​

7. Import folders and groups

After you save the app, import the folders, groups, and enterprise roles you want to manage: on the app’s Assets tab, select Import assets, and turn on requests for them. Opal pulls access only for imported items, so collaborators and members appear after the next sync.

​

Troubleshooting

Opal shows Box’s own error message. Look for the Box error code it contains:

​

Limits

Box allows 1,000 API requests per minute per user, and Opal makes every call as the service account. Sync cost grows with the number of groups and folders Opal manages, not with the number of files in your enterprise. Box pages groups and group members by offset up to 10,000, so the sync fails for an enterprise with more than about 11,000 groups, or a group with more than about 11,000 members.