> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/box.md).

# Box connector

Configure the Box connector to provision users and groups to Box using a Platform App with JWT server authentication.

The **Box connector** (`box-connector-rabbitmq`) provisions users and groups to [Box](https://www.box.com/) using the official Box Java SDK. It authenticates as a **Box Platform App with Server Authentication (JWT)** at the enterprise level, so no interactive login is involved.

| Operation                           | Supported |
| ----------------------------------- | --------- |
| Create / update user (Save)         | ✅         |
| Delete user                         | ✅         |
| Suspend / resume user               | ✅         |
| Reset password                      | ✅         |
| Search users                        | ✅         |
| Login                               | ✅         |
| Test connection                     | ✅         |
| Group create/update, delete, search | ✅         |

## Use cases

* Automating the **joiner/mover/leaver lifecycle for Box accounts** — create, update, disable, and remove Box users as part of provisioning.
* Managing **Box group memberships** from OpenIAM roles and groups.
* Importing existing Box users and groups into OpenIAM via synchronization for visibility and access review.

## Versions and compatibility

The end application is **Box**, reached through Box's own Java SDK rather than by building REST calls directly. What the connector supports is therefore what the bundled SDK supports.

<table><thead><tr><th width="177">Property</th><th>Value</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>Box</td></tr><tr><td><strong>Interface</strong></td><td>Box Java SDK, bundled at version <strong>4.8.0</strong></td></tr><tr><td><strong>Host</strong></td><td>Box's own API endpoints, resolved by the SDK</td></tr></tbody></table>

{% hint style="info" %}
Because the SDK is bundled with the connector, upgrading it is a connector release rather than a configuration change. A Box API capability newer than SDK 4.8.0 is not reachable until the connector ships a newer SDK.
{% endhint %}

## Prerequisites

You need a **Box Platform App** with **Server Authentication (JWT)**, created in the Box Developer Console, and network access from the connector host to the Box API (`api.box.com`, HTTPS).

{% stepper %}
{% step %}
Give the app **App + Enterprise access** and the scopes to **manage users** and **manage groups**.
{% endstep %}

{% step %}
Generate (or upload) the app's public/private keypair.
{% endstep %}

{% step %}
Download the app's configuration as JSON (**App Settings** → download the settings JSON) — it contains the client ID/secret, the app-auth keypair, and your enterprise ID.
{% endstep %}

{% step %}
Have a Box admin **authorize the app** in the Box Admin Console (custom apps must be authorized by client ID before the enterprise connection works).
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
The settings JSON contains the app's **private key and client secret** — treat it as a secret. Restrict filesystem permissions on the connector host and do not commit it to source control.
{% endhint %}

## Installing the connector

### Kubernetes

In Kubernetes deployments, the connector is deployed as part of OpenIAM — enable it in your deployment configuration; no separate installation is required.

### RPM

Run the connector JAR directly:

{% code overflow="wrap" %}

```bash
java -Dlogging.level.root=INFO -Dconfpath=/data/openiam/ -jar box-connector-rabbitmq.jar > box.out &
```

{% endcode %}

Or, when managed by systemd, use the connector service unit (`openiam-connector@box-connector-rabbitmq`). To deploy on a separate host, see [Connectors via RPM](/installation/rpm/rpm-single-node/add-a-connector.md).

## Starting, stopping, and restarting

<table><thead><tr><th width="181">Deployment</th><th>Commands</th></tr></thead><tbody><tr><td>RPM (systemd)</td><td><code>systemctl start|stop|restart openiam-connector@box-connector-rabbitmq</code></td></tr><tr><td>RPM (manual)</td><td>Start with the <code>java -jar</code> command above; stop by killing the process.</td></tr><tr><td>Kubernetes</td><td><code>kubectl rollout restart</code> the connector deployment.</td></tr></tbody></table>

## Command-line parameters and properties

The connector is a Spring Boot application. Its defaults ship inside the jar, and you override them in either of two places:

* **An external property file**, read at `${confpath}/conf/properties/box-connector-rabbitmq.properties`. The file is optional, and `confpath` is itself a system property, set with `-Dconfpath=/data/openiam/`.
* **Directly on the command line**, as `-D` arguments, which win over the file.

{% code overflow="wrap" %}

```bash
java -Dconfpath=/data/openiam/ -Dlogging.level.root=INFO -Dorg.openiam.connector.queue=BOX_Connector_1_Request -jar box-connector-rabbitmq.jar
```

{% endcode %}

<table><thead><tr><th width="382">Property</th><th>Default</th></tr></thead><tbody><tr><td><code>org.openiam.connector.queue</code></td><td><code>BOX_Connector_1_Request</code></td></tr><tr><td><code>org.openiam.connector.queueResponseName</code></td><td><code>BOX_Connector_1_Response</code></td></tr><tr><td><code>org.openiam.connector.name</code> / <code>.type</code></td><td><code>Box</code> / <code>Box Connector</code></td></tr></tbody></table>

The connection details themselves are **not** set here — they are managed system parameters, covered under [Configuring the managed system](#configuring-the-managed-system).

## Verifying the connector is running

{% stepper %}
{% step %}
In the Webconsole, open the managed system — the **Running connector status** indicator must be green.
{% endstep %}

{% step %}
Click **Test Connection** — it must return success.
{% endstep %}

{% step %}
In the RabbitMQ management console, confirm the `BOX_Connector_1_Request` queue exists and has a consumer.
{% endstep %}

{% step %}
Check the connector log for startup errors.
{% endstep %}
{% endstepper %}

## Troubleshooting

| Symptom                                                                        | Likely cause                                                                                       | Resolution                                                                                                      |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Every operation fails with `INVALID_CONFIGURATION` — *"Config path is empty!"* | The `CONFIG_PATH` managed-system attribute is missing or empty                                     | Add the attribute with the absolute path to the settings JSON.                                                  |
| Connector log shows *"Cannot find file"* / *"Cannot read the file"*            | The settings JSON is not at the configured path on the **connector host**, or permissions block it | Fix the path/permissions — remember the file must live where the connector runs, not where the Webconsole runs. |
| Box API rejects the connection                                                 | The app is not authorized in the Box Admin Console, or lacks scopes                                | Authorize the app by client ID and grant manage-users/manage-groups scopes.                                     |
| Connector never receives messages                                              | Queue-name mismatch                                                                                | The connector record's queue must equal `BOX_Connector_1_Request` exactly.                                      |

See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes).

## Registering the connector in OpenIAM

Register the connector under **Provisioning → Connectors** and attach it to the managed system — see [Registering the connector](/administration-guide/lifecycle/connectors-and-managed-systems.md). Match the queue name exactly:

## Configuring the managed system

{% stepper %}
{% step %}
Copy the downloaded Box settings JSON to the **host where the Box connector runs**, for example `/opt/openiam/conf/box/box_config.json`.
{% endstep %}

{% step %}
In the Webconsole, create a managed system for Box and select the **Box Connector**.
{% endstep %}

{% step %}
Add the managed-system attribute that points the connector at the credentials file:
{% endstep %}
{% endstepper %}

<table><thead><tr><th width="205">Managed-system attribute</th><th width="116">Required</th><th>Value</th></tr></thead><tbody><tr><td><code>CONFIG_PATH</code></td><td>Yes</td><td>Absolute path to the Box JWT settings JSON file on the connector host.</td></tr></tbody></table>

The standard URL/login/password connection fields are not used for authentication. The connector caches the Box connection per managed system and re-reads the configuration file when the path or managed system changes.

## Attribute mapping and policy map

Map OpenIAM user attributes to Box user fields (name, login/email, status) in the managed system's [policy map](/administration-guide/lifecycle/policy-map.md). Group assignments provision Box group memberships.

## Reconciliation and synchronization

The search operations supply Box users and groups as source records. Configure a sync against the managed system as described in [Configuring synchronization](/administration-guide/lifecycle/synchronize-and-import-data.md) to import Box accounts and groups into OpenIAM.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/connector-configuration/box.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.