# Box

The Veza integration for Box gathers Box Users, Groups, Roles, and Folders from the storage platform. Search, Insights, and Workflows for Box provide the ability to:

* See all Box users with administrative privileges on a Box tenant
* Review folders that have external guest collaborators.
* Review folders with Internal guest collaborators.
* Map Okta and Azure AD users and local Box users to ensure there are no local-only users.
* Create reports and rules for Box administrators and external collaborators

This guide includes steps to create a Box App to enable the connection, and configure the integration for Veza. See [Supported Entities](#supported-entities) for more details.

### Configuration - Box

> The Veza Box integration is compatible with Box, Business, Business Plus, Enterprise, and Enterprise Plus account types. Individual and Team Accounts are not supported.

The integration uses a [Box Custom App](https://developer.box.com/guides/applications/custom-apps/) to collect metadata. To create this read-only service principal:

**Box enforces a monthly limit of 50,000 API calls per Box user and App. You can configure more than one Veza Box App if the limit is reached.**

1. Log in to your Box account and open the Developer Console.
2. Click the "Create New App" button and select "Custom App".
3. Select Server Authentication (with JWT) as the Authentication Method
4. Click "Create App".

Configure the custom app in Box:

1. For "App Access Level" select *App + Enterprise Access*.
2. Under the *Application Scopes* section ensure the following boxes are checked:
   * [ ] `Content Actions/Read all files and folders stored in Box`
   * [ ] `Administrative Actions/Manage Users`
   * [ ] `Administrative Actions/Manage Groups`
3. Under the Advanced Features section ensure the following boxes are checked:
   * [ ] `Make API calls using the as-user header`
   * [ ] `Generate user access tokens`
4. Save the changes.

Generate a key pair and authorize the custom app:

1. Under *Add and Manage Public Keys* click *Generate a Public/Private Keypair*. A JSON file will be downloaded automatically, containing the private portion of the key and passphrase.
   * Optionally, you can upload an existing key pair, download the configuration file manually, and complete the key portion.
2. Under the *Authorization* tab click *Review and Submit* to make your new app available.
3. From the Box Admin console, navigate to *Integrations* > *Platform Apps Manager* to see the pending authorization.
4. Click on the integration, then click *Authorize* to enable the app for your Box environment. Click *Authorize* again to confirm the changes.

The JSON file downloaded in step 1 contains the necessary configuration information for setting up the integration in Veza:

```json
{
  "boxAppSettings": {
    "clientID": "<clientID>",
    "clientSecret": "<clientSecret>",
    "appAuth": {
      "publicKeyID": "<publicKeyID>",
      "privateKey": "<privateKey>",
      "passphrase": "<passphrase>"
    }
  },
  "enterpriseID": "123456"
}
```

### Configuration - Veza

1. In Veza, go to Configuration > Integrations
2. Click *Add New* and choose *Box* as the integration type
3. Complete the required fields:

| Field                                  | Description                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------- |
| Name                                   | Display Name                                                                          |
| Enterprise ID                          | Box Enterprise ID                                                                     |
| App Configurations                     | One or more Box Apps used for discovery (see note on API limits)                      |
| Include Non-shared Items               | Whether to parse objects that can only be accessed by their owners                    |
| Include External Collaborator Details  | Whether to parse full details for external collaborators                              |
| Folder extraction maximum depth        | Maximum depth to extract for sub-folders. Setting to 0 will limit to home folder only |
| Disable extraction of home/all folders | Disable user folder extraction. Will only extract Enterprise Users, Groups and Roles  |

### Supported Entities

* Box Enterprise
* Box User
* Box Group
* Box Role
* Box Effective Permission
* Box Folder
* Box Home Folder

Entity Attributes and notes:

#### Box User

A Box user represents an account on the platform used to access personal files and collaborate with others.

| User Properties                     | Details                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------ |
| `status`                            | Box status string, `active`, `inactive`, `cannot_delete_edit`, `cannot_delete_edit_upload` |
| `is_exempt_from_login_verification` | Indicates whether the user must use two-factor authentication (boolean)                    |
| `role`                              | The user's Box role                                                                        |

Only users from the enterprise are represented as graph entities. External collaborators are shown in Folder properties.

#### Box Role

For Box, roles are a set of permissions that can be assigned to a user or group of users, defining the actions an identity can perform, and what data they can access within the platform.

| Role Properties      | Details                         |
| -------------------- | ------------------------------- |
| `Permissions [0-99]` | List of System role permissions |

Box User(s) and Group(s) can have a Role defined on Folder(s). Roles can be `owner`, `co-owner`, `editor`, `viewer uploader`, `previewer uploader`, `viewer`, `previewer`, or `uploader`.

#### Box Folder

Box folders are containers used to organize and store files and documents. Folders can be organized hierarchically to create a logical structure for file storage.

A Box User's folders can be private or shared with specific collaborators or groups. Users can set permissions for each folder, determining who has access to the folder and what actions they can perform on the files within the folder.

Box Folder entity attributes indicate external collaborators: `HasExternalCollaborators`, and a list of `ExternalCollaborators` containing user IDs, and possibly name and e-mail (if "Include External Collaborator Details" is enabled).

In Graph search, you will be able to see the folder contents of all users' root (home) folders. Box Home Folder entities represent the root-level folder for each Box User.

| Folder Properties            | Details                                  |
| ---------------------------- | ---------------------------------------- |
| `has_external_collaborators` | True if there are external collaborators |
| `external_collaborators`     | List of external collaborators           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/box.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.