Box Connector

The Box connector enables use of a Globus data access interface on an Box storage system, via the Box API.

The Box connector is a premium feature available only to Globus subscribers, and is thus only available for Managed Endpoints.

The installation must be done by a system administrator, and has the following distinct set of steps:

  • Create and authorize a Box JWT application for enterprise authentication or a Box OAuth2 application for OAuth2 user authentication.

  • Create a Box Storage Gateway

  • Create a Box Mapped Collection

Box Connector Virtual Filesystem

The Box provides a cloud storage system that allows users to create and share files and folders. While the Box services supports many features such as bookmarks and file versioning, the Box Connector only supports access to the latest version of files stored in the Box service.

Create a Box Application

The Box Connector uses the Box API to interact with the Box web service. In order to do this, you must create an application configuration on the Box developers console and enable the features that the Box Connector needs.

As of GCS version 5.4.54, you can choose either OAuth2 user authentication or Enterprise authentication. With OAuth2 user authentication, users are prompted to authenticate to Box on first access of a collection. With Enterprise authentication, users only authenticate to their Globus account, and the application credentials allow Globus Connect Server to authenticate to the Box service on behalf of each user.

OAuth2 Application

  • Open the Newapp Page

  • Select Custom App for the App Type

  • Select User Authentication (OAuth 2.0) for the Authentication Method

  • Enter a name for your app and click Create App

  • Update your app configuration as follows:

    • Add your Redirect URI under OAuth 2.0 Redirect URI. This was displayed upon completion of endpoint setup.

      If you don’t have that value handy, you can run the command

      globus-connect-server endpoint show

      You’ll see output that looks something like this:

      Display Name:    Test Endpoint
ID:              669ec822-ca79-455c-89a7-cccb7aefbf8e
Subscription ID: 6e62e6d7-e368-45f4-a23d-fb41243e8005
Public:          True
GCS Manager URL: https://21542.data.globus.org

      You can construct the auth callback URL by appending /api/v1/authcallback to the value of the GCS Manager URL. In this example case, the result is https://21542.data.globus.org/api/v1/authcallback.

    • Check only the following Application Scopes

      • Read all files and folders stored in Box

      • Write all files and folders stored in Box

    • Make sure to save your changes

  • Copy the Client ID and Client Secret under the OAuth2.0 Credentials section. You will need these values when creating the Box Storage Gateway.

  • Depending on the settings in your enterprise, you may need to authorize the application using the Client ID. This is not necessary with the default enterprise settings.

Enterprise Application

  • Open the Newapp Page

  • Select Custom App for the App Type

  • Select Server Authentication (with JWT) for the Authentication Method

  • Enter a name for your app and click Create App

  • Update your app configuration as follows:

    • Set the App Access Level to App + Enterprise Access

    • Check only the following Application Scopes

      • Read and Write all files and folders stored in Box

      • Manage Users

    • Under Advanced Features, check Generate User Access Tokens

    • Make sure to save your changes

  • Copy the Client ID under the OAuth2.0 Credentials section. You will need this to Grant the Box Application access to your Enterprise

  • Under the Add and Manage Public Keys section press Generate a Public/Private Keypair. This will prompt you (you may need to allow a popup) to save a .json configuration file on your machine. You will need this file when creating the Box Storage Gateway.

Grant the Box Application access to your Enterprise

In order for the Box connector to access files owned by users of your enterprise, the application created in the previous step must be allowed access by the enterprise administrator. This is always required for an Enterprise application, but is not required for an OAuth2 application with the default Box enterprise settings. If authorization is required, the Box administrator must perform the following steps:

  • Open the Enterprise App Settings page for your Box Enterprise account

  • Under the Custom Applications section, select Authorize New App

  • When prompted for the API Key, enter the Client ID for the Application from the Create a Box Application step.

Note
This authorization action must be repeated by the enterprise administrator if you ever make any changes to the box application or its requested scopes.

Box Configuration Encryption

All configuration information, including Box secrets and user credential information, is encrypted with a secret key on the node servicing the request before storing it locally and uploading it to GCS cloud services for distribution to other nodes in the endpoint. The encryption key is only available locally to the node and is secured such that only the node admin has access.

Storage Gateway

A Box Connector Storage Gateway is created with the command globus-connect-server storage-gateway create box, and can be updated with the command globus-connect-server storage-gateway update box.

Before looking into the policy options specific to the Box Connector, please familiarize yourself with the Globus Connect Server v5 Data Access Guide which describes the steps to create and update a storage gateway, using the POSIX connector as an example. The commands to create and update a storage gateway for the Box Connector are similar.

Box Connector Storage Gateway Policies

The Box Connector has policies to set the box application configuration. The Box connector may authenticate users to Box in two different modes. In OAuth2 mode, users individually authenticate to their Box account with a web based OAauth2 login before using the collection. In Enterprise mode, users provide no additional authentication before using the collection and are mapped to their Box account based on their Globus username. The configuration for either mode is described below.

Box OAuth2 Settings

The --box-client-id and --box-client-secret command-line options configure the Box OAuth2 application on the storage gateway. These will be used to authenticate users with the Box API.

In OAuth2 mode, users individually authenticate to their Box account with a web based OAuth2 login before using the collection. The user’s Box account must match the username mapped from their Globus identity, unless the --box-allow-any-account command-line option is set.

Example 1. Box OAuth2 Settings

After creating the OAuth2 application on the Box Developer console, note the client id and secret. We’ll need to pass these to the command line when creating a Box Storage Gateway.

--box-client-id 5hh1d5odqebjjg4howv6obf8zluz --box-client-secret E90n2ah8g6edMG8Kaaw0EUZwgrpO

Box Enterprise Settings

The --box-settings command-line option is used to pass the key information created when the Box application is created to be used by the Box Connector.

Example 2. Box Settings

After creating the keypair on the Box Application configuration screen, the browser will download a file with a name with the suffix _config.json. We’ll need to pass path to this file to the command line when creating a Box Storage Gateway. For our example, we’ll assume the file downloaded has a name 996511312_fb430f1403fb_config.json.

--box-settings file:996511312_fb430f1403fb_config.json

Creating the Storage Gateway

Now that we have decided on all our policies, we’ll use the command to create the storage gateway.

% globus-connect-server storage-gateway create box \
    "Box Storage Gateway" \
    --domain example.org \
    --box-settings file:996511312_fb430f1403fb_config.json

Storage Gateway Created: 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab

This was successful and outputs the ID of the new storage gateway ( 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab in this case) for our reference. Note that this will always be a unique value if you run the command. If you forget the id of a storage gateway, you can always use the command globus-connect-server storage-gateway list to get a list of the storage gateways on the endpoint.

You can also add other policies to configure additional identity mapping and path restriction policies as described in the Globus Connect Server v5 Data Access Guide.

Note that this creates the storage gateway, but does not yet make it accessible via Globus and HTTPS. You’ll need to follow the steps in the next section.

Collection

A Box Collection is created with the command globus-connect-server collection create, and can be updated with the command globus-connect-server collection update.

As the Box Connector does not introduce any policies beyond those used by the base collection type, you can follow the sequence in the Collections Section of the Globus Connect Server v5 Data Access Guide. Recall however, that the paths are interpreted as described above in Box Connector Virtual Filesystem.

Appendix A: Document Types for the Box Connector

BoxStoragePolicies Document

Connector-specific storage gateway policies for the Box connector.

One of the following schemas:

​

{
  "DATA_TYPE": "box_storage_policies#1.0.0",
  "boxAppSettings": {
    "appAuth": {
      "passphrase": "string",
      "privateKey": "string",
      "publicKeyID": "string"
    },
    "clientID": "string",
    "clientSecret": "string"
  },
  "enterpriseID": "string"
}