App Auth

Overview

App Auth allows your application to request OAuth2 access tokens necessary to make calls to the Box Content API. Your application may request one of two token types: an enterprise access token and a user access token.

  • Enterprise access token: Used to provision users via the /users endpoint.
  • User access token: Used to make API calls to endpoints of the Content API.

Creating App Users and Managing Your Enterprise

Using the enterprise access token, you can create new App Users for your enterprise, as well as manage groups and other enterprise settings. To request this token, you will need to specify the associated enterprise ID. This can be found in the Admin Console.

Performing User-Based Actions

Once you have created an App User, you can then request a user access token via the App Auth feature, which will return the OAuth2 access token for the specified user. This token is used to take user-specific actions (e.g., upload/download content, make comments, assign tasks, share with other users, etc.).

Your service will authenticate to Box by sending a JSON Web Token to the /token endpoint containing a JSON payload that includes the API key, enterprise_id or user_id, and additional claims, and sign it using the private key of an RSA keypair. Box then verifies the identity of your application using the public key specific to your application.

Generating an RSA Keypair

The first step in setting up App Auth is to create the RSA private-public keypair used to sign and authenticate the JSON Web Token (JWT) assertion. This key must be in the PEM format.

We recommend generating the RSA keypair using the OpenSSL toolkit.

For Mac and Linux/Unix-based Systems

You can run the OpenSSL commands from terminal below to generate an RSA Keypair.

For Windows Systems

Install and use the Cygwin package to run the OpenSSL RSA keypair commands below.

openssl genrsa -aes256 -out private_key.pem 2048
openssl rsa -pubout -in private_key.pem -out public_key.pem

Note:

To modify the output PEM files, simply change the filenames in the commands above.

Example Public Key Format

If properly generated, the RSA public key should look like the example public key below:

RSA keypair must be in PEM format

Be sure to include the full header and footer: '-----BEGIN PUBLIC KEY-----' AND '-----END PUBLIC KEY-----'

Submitting the Public Key

Once you've generated a public key, you will need to connect your app to an enterprise instance. To do this, you will need to provide an API Key with your Box Admin. If you are a Box Admin, you can follow these instructions to enable custom apps for your enterprise.

To connect your app to an enterprise:

1) In your app's configuration, scroll down to the Public Key Management section.

2) Select Add Public Key.

3) Enter your public key and click Verify.

Upon successful verification of the RSA public key's encryption level and format, the Verify button will indicate successful verification as shown below.

Common Errors

Common errors for publc key entry include "Insufficient Encryption" and "Invalid Format."

4) Click Save.

Your Public Key and Key ID will now display in your app settings

Share your API Key with your admin to connect to your enterprise. If you are the admin for your enterprise, follow these instructions to enable custom apps for your enterprise.

Key ID Required

You will need to specify the Key ID in the "kid" claim of the JSON Web Token.

Constructing the JWT Assertion

Once you have created the RSA keypair and submitted the public key to Box, you can request access for Enterprise and User Access tokens using the JWT grant.

Every JWT assertion is composed of three components, the header, the claims, and the signature.

  • The header specifies the algorithm used for the JWT signature.
  • The claims contain the information necessary to authenticate and provide the correct token.
  • The signature is used to verify the identify of the application and is verified using the public key.

To construct the JWT assertion, these three components must be base64 encoded and concatenated using a “.” separator:

<base64URLencoded header>.<base64URLencoded claims>.<base64URLencoded signature>

Once encoded and concatenated, the JWT assertion will look like this:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9eyJpc3MiOiJ2Z3.
B2bWFvaDJjZ2ZjNGRuMzFnMWx0cmlhbmdlZCIsInN1YiI.
6IjE2ODczOTQzIiwiZXhwIjoxNDI5MDM3ODYwLCJqdGkiOiJ

JWT Libraries

Fortunately, there are many libraries available for easily constructing the JWT assertion. These can be found here.

Constructing the Header

Header Attributes

Parameter
Type
Description

alg

required

String

The algorithm used to verify the signature. Values may only be set to: “RS256″, “RS384″, or “RS512.″

typ

required

String

Type of token. Default is “JWT” to specify a JSON Web Token (JWT).

kid

required

String

Public Key ID generated by Box and provided upon submission of a Public Key. Identifies which Public Key a client is using.

Example Header

{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "8nkq5s45"
}

Supported Algorithms

We currently support the following algorithms: “RS256″, “RS384″, and “RS512″. Other values entered for the alg parameter will return a “400 Bad Request” with “invalid_grant” as the error code since it specifies a value for a parameter that is unsupported.

Finding the Key ID

The Key ID is displayed under the Public Key Management section of the Edit Application page.

Constructing the Claims

Claims Attributes

Parameter
Type
Description

iss

required

String

The API key of the service that created the JWT assertion.

sub

required

String

  • enterprise_id for a token specific to an enterprise when creating and managing app users.
    • app user_id for a token specific to an individual app user.

box_sub_type

required

String

“enterprise” or “user” depending on the ID that was passed in the sub claim.

aud

required

String

Always “https://api.box.com/oauth2/token” for OAuth2 token requests

jti

required

String

A unique identifier specified by the client for this JWT. This is a unique string that is at least 16 characters and at most 128 characters.

exp

required

NumericDate

The unix time as to when this JWT will expire. This can be set to a maximum value of 60 seconds beyond the issue time. Note: It is recommended to set this value to less than the maximum allowed 60 seconds.

iat

optional

NumericDate

Issued at time. The token cannot be used before this time.

nbf

optional

NumericDate

Not before. Specifies when the token will start being valid.

Based on the above parameters, we can construct an example set of JWT claims:

{
    "iss": "veds3i33z1fx6dle7iv3z344zbwy6miv",
    "sub": "54",
    "box_sub_type": "user",
    "aud": "https://api.box.com/oauth2/token",
    "jti": "M4yeY3W63TxHa9jFek85",
    "exp": 1428699385
}

Constructing the OAuth2 Request

The OAuth2 request returns only an access token and no refresh token. To request the access token, the signed JWT should be sent to the /token endpoint of the Content API via a POST request. Multiple access tokens can be live at any given time and the expiration for each token is independent of the expiration of any other access tokens.

Parameter
Type
Description

grant_type

required

String

Always set to “urn:ietf:params:oauth:grant-type:jwt-bearer”

client_id

required

String

The API Key of the service making the JWT request

client_secret

required

String

The secret of the service making the JWT request

assertion

required

String

The JWT Assertion mentioned above

Example 'POST' to the '/token' endpoint

POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=<JWT>&
client_id=<client_id>&
client_secret=<client_secret>
curl https://api.box.com/oauth2/token \
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&assertion=YOUR_JWT_ASSERTION' \
-X POST
{
   "access_token": "mNr1FrCvOeWiGnwLL0OcTL0Lux5jbyBa",
   "expires_in": 4169,
   "restricted_to": [],
   "token_type": "bearer"
}

App Auth


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.