Construct JWT Claim Manually

Box offers an authentication model that allows applications to authenticate directly to Box using a JSON Web Token (JWT) signed with an RSA key. This authentication method is meant for server-to-server applications and replaces the first leg of the standard 3-legged OAuth 2.0 process in which users grant an application authorization to access the their Box account. Because your application authenticates directly to Box, this process removes the friction of multiple logins and services for your users.

This guide will take you through the necessary steps to authenticate using OAuth 2.0 with JSON Web Tokens (JWT). If you have not already configured your application for Box Platform, please complete the prior tutorial.

Overview

OAuth 2.0 with JWT allows your application to request OAuth 2.0 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

When an application is created in the Box Developer Console, a Service Account is created. Service Accounts are a user-based representation of your app within a Box Enterprise (EID). Using the Service Account, you can obtain an enterprise access token.

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 under the Account Info tab. You will only be able to access this tab if you are the Admin of the account.

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 Client ID, 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.

1. Generating an RSA Keypair

The first step is to create an RSA private-public keypair used to sign and authenticate the JSON Web Token (JWT) assertion. The private key is used to sign your requests and is verified by the public key, which you provide to Box. Be sure to protect your private key as this is the only means to verify your application's identity.

Box offers the ability to create your own RSA keypair through the developer console. We do not store the private key generated, so remember to keep note of it. In order to do this:

  • Navigate to the configuration page for your application
  • Scroll down to Add and Manage Public Keys
  • Select Generate a Public/Private Keypair

Box will generate your public / private key pair, upload the public key to our system and the download a file with your private key and application settings. If you have done this, you can skip ahead to Granting Access in Enterprise Admin Console.

If you choose to generate your own RSA key pair, you can follow the instructions below. To do this, we recommend RSA keypair using the OpenSSL toolkit.

For Mac and Linux/Unix-based Systems

You can run the OpenSSL commands to generate an RSA Keypair. Use the same examples as shown under the "For Windows Systems" section below:

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-----'

2. Submitting the Public Key

Once you've generated a public key, you will need to save it in your application configuration.

1) Go to the developer console and select your Box Platform application.

2) Scroll down to the Add and Manage Public Keys section.

3) Select Add Public Key as shown below.

4) Enter your public key and click Verify and Save.

Common Errors

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

Insufficient Encryption indicates you must use a higher bit encryption algorithm. Invalid format indicates that the Public Key is not in the proper PEM format (as shown below).

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

Key ID Required

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

3. Grant Access in Enterprise Admin Console

In order to begin creating App Users in an enterprise, authorization for your application must be granted in the Enterprise Admin console. If you are building with your own developer enterprise, follow the instructions below.

  1. Log in to Box and select Admin Console at the top of the screen.
  2. Go to the Enterprise Settings and click on Apps.
  3. Within the Custom Applications section, choose Authorize New App.
  4. Enter the Client ID for the app you would like to enable. This will display the requested Applications Scopes and User Access Level* that determines which users the app has control over. The determine what permissions an Application receives in the enterprise and which sets of users an application may access and modify.
  5. Once Authorized, the app will be enabled within your Developer enterprise.

4. Constructing the JWT Assertion

Once you have created the RSA keypair and submitted the public key to Box, you can request Enterprise and User OAuth2.0 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:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleV9pZF9oZXJlIn0.
eyJpc3MiOiJjbGllbnRfaWRfaGVyZSIsInN1YiI6ImVudGVycHJpc2VfaWRfaGVyZSIsImJveF9zdWJfdHlwZSI6ImVudGVycHJpc2UiLCJhdWQiOiJodHRwczovL2FwaS5ib3guY29tL29hdXRoMi90b2tlbiIsImp0aSI6ImFueV91bmlxdWVfc3RyaW5nIiwiZXhwIjoxNTE1NDMzMDU3fQ.
r5iNQw2RYM7bbaohAzV9XFSf4DUWQLpI_ZqtRVgclTBiOJ6WLDuSnmPKwp1Z7fRVIWdwSuOo0Mo1tFC6HwS2UMu1dn6ePRwuhe5dfSd1kvR2Yo0WiUrVl3G7PfKUWtypW5CZGGdWb9B0PZM_zi_hyzSqxfjl3YvS44wui4TcgLEwpeoky_77H6UlMWMntMPNDnUS7C-dc9PQzZqFyQqFo9x7xs4NUpjz9TxHEr1heaGbQ00ex6Wk0Cvz_MBvOh1UYmS6qhOQ180T5rwgCO8OxJEIf2Hrbr5piIsKgAt4GVpZpPo456nG0eZo6fjaxG2TiqMxvZ3fnwWsFhHb7S0RDg

JWT Libraries

Fortunately, there are many libraries available for easily constructing the JWT assertion. These can be found here. Our SDKs also provide methods that will handle authentication with JWT.

5. Constructing the Header

Header Attributes

Parameter
Type
Description

alg

required

String

The algorithm used to verify the signature. Only supports “RS256″, “RS384″, and “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.

6. Constructing the Claims

Claims Attributes

Parameter
Type
Description

iss

required

String

The Client ID 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 type of token being requested in the sub claim.

aud

required

String

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

jti

required

String

A universally 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
}

7. Constructing the Signature

The signature is constructed by concatenating the base64 url encoded header and claims, then encrypting it with the algorithm specified in the header (e.g. 'alg'). The algorithm specified in the header is the algorithm Box uses to verify the signature (only supports “RS256″, “RS384″, and “RS512″). This step is also where your public and private keys are used.

The private key is used to encrypt the base64 url encoded and concatenated header and claims, which is then able to be verified (decrypted and read) by Box, using the public key ID (specific to an application) from the header.

The signature must also be base64 encoded, just like the header and claims.

A sample JWT tool for exploring manual JWT creation is available at jwt.io.

Payload vs Claims

The terms "payload" and "claims" are interchangeable. Both refer to the same part of the JWT.

8. 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 Client ID of the application making the JWT request

client_secret

required

String

The Client Secret of the application 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"
}

9. Next Steps

You have now successfully set up your app's authentication, created a Service Account, and are ready to create your first App User. Complete the next tutorial to learn how to create your first App User and make your first API call.

Questions
If you have any questions, please visit our developer forum.

Construct JWT Claim Manually