Getting started with Box Python SDK and JWT

Server-side authentication using JSON Web Tokens (JWT) is the most common way to authenticate to the Box API. JWT is an open standard designed to allow powerful server-to-server authentication

In this article we will explore how to use the Box server side authentication with JSON Web Tokens (JWT).

Comparing with Box OAuth 2.0, where the application is making call to the API on behalf of the user within the user security context, when using the Box JWT server side authentication your application has its own security context and it may or may not act on behalf of a specific user.

Server-side authentication with JWT is the ideal authentication method for apps that:

• Work with users that don’t have a Box account
• Want to use their own identity system
• Don’t want users to be aware they are using Box
• Want to store data within the application’s Box account and not within the the user’s Box account

Requirements

Sample app

You can take a look at the end result of this exercise by cloning this repo, see the readme for more information.

Create a Box app

You’ll need a Box application configured to use JWT.

First you need to have a Box.com account.

Once you have an account, go to the Box developer console, and create or configure an app:

Although for this example the default application scopes are fine, depending on the features of your app you may want to change the application scopes:

Set your CORS domain:

Generate a public/private key pair:

A config.json file is downloaded, and it contains the encrypted private key. This key is not stored anywhere else, so if you loose this files you’ll have to generate a new key pair.

We will use this file later to configure the authentication.

Next, submit the app for authorization:

Your Box.com enterprise administrator will get an email with your request, and can proceed with the app authorization. If you are using your own developer account you can authorize your own app.

Navigate directly to your admin console application manager:

Box server side authentication with JWT

Authenticating to Box using JWT is a simple and straightforward process.

Step 1: Authenticate with JWT

The Box Python SDK JWTAuth class will handle this:

Use the from_settings_file() method to read the config.json file you downloaded.

Pass a callable to store the access token using the store_tokens parameter.

Pass an existing access token. The JWTAuth class checks if we still have a valid access token and if not, gets a new one automatically.

Optionally you can also specify each parameter manually, for example:

Note — you have to have a path to the encrypted private key file.

The authenticate_instance() method triggers the authentication API call and in return you get an access token.

Step 2: Make calls to the API

The Client class is the gateway to make calls to the API, and accepts a JWTAuth instance. It can be as simple as:

When using JWT, there is no refresh token (like in OAuth 2.0), the JWT authentication will be used again when the access token has expired.

Putting it all together

In this example I’m using UI Elements JavaScript components that require an access token. Like any other JavaScript object these can be inspected using the browser tools.

Token down scoping

In order to get a more restrictive access token, we take the access token and we “down scope” it using the specific grants for the UI Elements. Each Element supports a variety of access levels.

In the above example I’m experimenting with flask_caching instead of checking if the token has expired.

Using the down scoped access token

So whenever the app needs an access token to use in the UI Elements, it can just call the method jwt_downscoped_access_token_get().

Using the Client class

If your app needs to use the API then it just needs to instantiate the Client class.

For example when the app creates a demo folder to hold the uploads:

Or when the app retrieves the files in the demo folder:

This JWT example is combining Box Python SDK and UI Elements.

This combinations gives your app the ability to act as a Box user, with its own files, folder ownership and all the other Box features.

It also allows your application users to interact with content stored at Box.com without forcing you to re-invent the wheel and design all the interfaces need.

The Box Python SDK helps you manage the authorization process and also provides access to the entire Box.com API.

Happy App Building!