JWT Application Setup

This guide will walk you through creating a new JWT application and configuring it within your enterprise.

Complete the following steps to create and configure a new JWT application

  1. Create and Configure a JWT Application.
  2. Generate a public / private keypair to sign and authenticate your app requests.
  3. Grant access for the application in your enterprise.

Step 1: Create and Configure a JWT Application

To create a new JWT application follow the proceeding steps:

  1. Go to the Box developer console and click on the Create New App option.
  2. On the next page, click on the type of application you'd like to build (e.g. Custom App) and click the Next button.
  3. On the authentication method page that comes up, click on the option for OAuth 2.0 with JWT and click the Next button.
  4. Give your application a unique name, click the Create App button, then click the View Your App button on the next page.

Your newly created JWT application will be presented on the Configuration page, allowing you to further configure it. To do so, adjust these settings:

  • Application Access: By default your application will be set to application level access. This means that your application will only be able to work with users that it creates. To also work with existing user in the entire enterprise, you may select the enterprise option.
  • Application Scopes: These options represent what API endpoints / functionality that your application will have access to. See the scopes page for detailed information on each option.
  • Advanced Features: These two options will allow you to work with the users within your application. In most cases these options should both be turned on, unless the features are not needed.
    • Perform actions as users will allow your application to make API requests on behalf of a user, instead of the app itself.
    • Generate user access tokens will allow you to access APIs without the user having to log in with their credentials.

Once these options are configured, move on to the next step.

Step 2: Generate a Public / Private Keypair

There are two methods that may be used to generate an RSA keypair for your JWT application:

  • Use the config file generated during application setup (Recommended method).
  • Generate the public / private keypair manually.

Use an Application Config File

While creating your JWT application, an option is available to have Box create a config file for you, which includes your public / private keypair, as well as a number of other application details that will be used during authentication. This is the Box recommended method.

Complete the following steps to generate your config file:

  1. Click on your JWT app from the developer console.
  2. Click on the Configuration option from the left nav.
  3. Scroll down to the Add and Manage Public Keys section.
  4. Click on the button to Generate a Public/Private Keypair.

The config json file will start downloading. The contents of that file will look similar to the following:

{
  "boxAppSettings": {
    "clientID": "plb5ltfzq9bz7micz6x6p5zfnycw98e3",
    "clientSecret": "PCQNt3d6xym9JiiVGRqDpNcFryxKhfun",
    "appAuth": {
      "publicKeyID": "hs2c02ko",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n
                     MkiG9RefG12qasOn\nMBQGCCqGSIb3DQMHBAj/xheVHRkNNgSC
                     BMhL9TFI/pX0EVwkT44QyEOI9DuXIIlsg\nwqYR58DkP7ItCfZdFHq8
                     3pCwLjlvuRYsYGsb2F24OsLjCna0HsnpCbe4rvpedj7QE/aO\nN0xn8
                     p\nYnhxUWQzXy7ZnzYPn1wmtcaYwx+Ialn2tukqZCEpqrFf8guOjvBl
                     aPHcMGwYJab0\n26k=\n
                     -----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "176183e88324823d2318b74a1f376486"
    }
  },
  "enterpriseID": "13684983"
}

RSA keypair must be in PEM format

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

The information contained in the file will be used when going through the JWT authentication process.

Generate Keys Manually

The second method for generating your public / private keypair is to generate the keys manually, then attach them to your JWT application.

From a terminal window / command prompt, run the following commands:

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

For Windows Systems

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

Next, add the public key to your JWT application by doing the following:

  1. Click on your JWT app from the developer console.
  2. Click on the Configuration option from the left nav.
  3. Scroll down to the Add and Manage Public Keys section.
  4. Click on the button to Add and Manage Public Keys.
  5. In the window that opens, paste in the entire contents of your manually generated public key file.

Step 3: Grant Access for the Application in Your Enterprise

If You're Not the Enterprise Owner

If you do not own the enterprise account, such as if your Box account was created by your company, then you will need to have the admin of the enterprise enable your application using the instructions below, providing all required details from below for authorizing your app.

If you don't know your enterprise admin, go to the Box account settings page and scroll to the bottom. If an admin contact is set you should see contact information under "Admin Contact".

Once your keys have been generated, your JWT application will need to be authorized within your Box enterprise by your enterprise admin.

With access to the enterprise admin console, use the following steps to grant access to your application:

  1. Open the enterprise admin console business settings.
  2. Click on the Apps link in the nav at the top of the page.
  1. Scroll down to the Custom Applications section and click on the Authorize New App button.
  2. When asked for the API key, enter the client ID for the JWT application that you created during the first step.

Where's the Client ID?

To get your client ID, go to the developer console and select your JWT application. Once open, go to Configuration in the left nav and scroll down to the OAuth 2.0 Credentials section. The client ID will be present there.

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.

When Making Scope Changes to your Application

If you make changes to your JWT scopes at any time, you will need to reauthorize your application in the enterprise for those changes to take effect.

If You're Not the Enterprise Owner

If you're not the enterprise owner you will need to ask your enterprise admin to reauthorize your application using the instructions below. You may locate the admin contact using the instructions under this similar callout in step 3.

Use the following steps to reauthorize your application:

  1. Open the enterprise admin console business settings.
  2. Click on the Apps link in the nav at the top of the page.
  3. Scroll down to the Custom Applications section and click on the ellipses button to the right of your JWT application name.
  4. From the menu, select Reauthorize app to bring in the new scope permissions.

Next Steps

JWT Application Setup