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:
“I use a personal Box account”:
You will have to set up a Box-app, then authenticate to it.
“I use a Box account that an institution manages”:
Your institution may have set up an app already; you may be able to authenticate to it. If not, maybe you can create a Box-app or ask your Box-admin team to create one.
The type of Box-app you use may also depend your situation:
“I want to use boxr interactively, from my
local computer”:
We recommend you use a Box interactive-app; authenticate using
box_auth(). You can read more in this interactive-app article.
“I want to run an unattended scheduled process, e.g. a
report, from a remote machine using boxr”:
We recommend you use a Box service-app; authenticate using
box_auth_service(). You can read more in this service-app article.
“I want to use boxr interactively using a
remote machine, perhaps using RStudio Cloud or RStudio
Server.”:
You could go either way; this situation is covered in both the interactive-app article and the service-app article.
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: This is preferred for interactive use (this includes you hitting the “knit” button in the RStudio IDE). The user authenticates to the app interactively, using the “OAuth Dance”: a browser-window is opened to ask the user’s permission. The app has all the rights of the user who authenticates to it. The Box documentation on OAuth 2.0 apps has even more detail.
Service App: This is useful for unattended use, e.g. on a remote computer. A token (JSON file) is generated using the Box (or Box Enterprise) website. This token can be deployed to the (presumably remote) computer; there is no “OAuth Dance”. Because these apps can act on behalf of the Box system itself, we recommend that you configure the app with a minimal set of privileges, e.g. to access only the Box folder that the app will need. The Box documentation on JWT apps has even more detail.
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.
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.