Box Apps

Any time you interact with the Box API, you will be using a Box application, i.e. a Box-app. If you’ve already used boxr to authenticate with Box, you’ve already used a Box-app.

You can think of a Box-app as the door through which boxr functions can access Box. For the most part, boxr functions keep this “out-of-mind”. During authentication, Box-apps come to the fore.

Getting the authentication to work the first time is most difficult part of using this package. Once you get it working, it should just work.

How you deal with Box-apps may depend on your situation:

The type of Box-app you use may also depend your situation:

This vignette is about the two types of apps that boxr uses, how to authenticate to them, and the security considerations that go along with them:

Interactive App

An interactive-app is straightforward because it acts on behalf of the user who has authenticated to it, with the privileges of that user (those privileges in the scope of the app). To authenticate using an OAuth2 app, you can use the box_auth() function, which may invoke the “OAuth Dance”.

More than one user can authenticate to and use a given app; however, each user will be able to use the app only as them-self. There is a restriction: a Box app can handle no more than one request at a time; the greater the number of users of a given app, the greater the probability of a collision.

The authentication process for an interactive-app is easiest if you have physical control of the computer from which you are trying to authenticate, e.g. your laptop. If you are using a remote computer, e.g. RStudio Server, you can generate this token on a local computer, then upload the token to your RStudio Server.

Keep in mind that the token retrieved by box_auth() is as “powerful” as the user them-self; it should be treated with all due care. The user’s Box account is no more secure than the security of this token. By default, the boxr token is cached, unencrypted, in the user’s home directory, as ~/.boxr-oauth. Because it is unencrypted, you should take care not to commit this file to a git repository.

We recommend this as the first choice for authentication; it should work well in most situations, for most boxr users. More details on using and creating an interactive-app are given in the interactive-app article.

Service App

There may be situations you want to use boxr as a part of specific unattended tasks. Perhaps it is a scheduled report, perhaps a set of continuous-integration tests. Service-apps are designed for these situations, but they should be used with care - particularly because they are designed to run unattended, outside your daily attention.

This type of app uses a service account, which is associated with a Box account or a Box Enterprise account. A service account is similar to a user account, but with additional admin functionality. Service accounts are not linked to a particular user account, but they can be configured to act on behalf of any and all user accounts for that Box account. Hence, they have additional security considerations.

You can mitigate this security consideration by restricting the capability of a service-app so that its service-account cannot act only on behalf of a user-account, and can access only particular folders. Although it may be administratively-cumbersome, you might consider a separate service-app for each use-case. This way, if a token becomes comprised, the exposure is limited to that folder, that use-case.

The authentication-process for a JWT app is handled at the Box website, in an admin-console. Here, you can generate a token for your app, then download it so that you can deploy it for your use-case. You can do this once, in contrast with the “OAuth Dance” you need to undertake, from time-to-time, with a standard OAuth2 app.

A service-app, using JWT authentication, can work for unattended tasks, but please take care to give your app as little capability as needed. More details on using and creating a service-app are given in the service-app article.