Using Box as an Atlassian Forge OAuth Provider

OAuth systems are a very important facet of cloud development ecosystems, allowing both users and developers an easier integration point into products and their APIs. For developers, this often allows for a secure method of gaining access to a product’s API from a user’s context without having to roll their own service account or other manual authentication system. For users, this provides ease of access without sacrificing security, enabling them to login via the normal product’s methods without sharing their password with third parties. Across the board OAuth creates a standard that allows for companies to more easily enable third party integrations which in turn empowers their cloud ecosystem to greater heights.

With this in mind, we are going to go over how to allow your users to login to their Box accounts inside the Atlassian cloud ecosystem using Forge. To do this we will need to implement an OAuth setup reaching out to Box’s API from our Atlassian Forge application. This will allow users to access their Box account’s documents from within an Atlassian product. OAuth systems can potentially be tedious to implement since most API’s have a slight variation on the pattern. Thankfully, Atlassian has a custom provider system that makes integrating with a third-party OAuth system like Box a walk in the park.

Forge’s Custom   OAuth Provider System

Atlassian’s OAuth provider system, as a part of the Forge platform, provides this heightened security around authentication/authorization while also streamlining the development process of an integration with Atlassian products. The custom provider system allows you to declaratively setup OAuth API endpoints for one or more providers in your Forge manifest by setting up the following actions: “authorization”, “exchange”, “refreshToken”, “revokeToken”, and “retrieveProfile”. This system also allows you to set specific user scopes and allows for custom mapping of user profiles between Atlassian and the provider.

Check out the official documentation to dig deeper into the specifics of the custom OAuth provider system

Wiring the Forge OAuth Provider System to the Box API

Before being able to integrate Box as an OAuth provider in your Forge application you must have a Box application. See below for the steps to create and configure a Box application which we can later use for the Forge OAuth setup.

Box Developer Console

For this section you will need access to Box Developer Console, whether that is through a company or a personal domain.

1. To get started you will need to have / create a “Custom App” on the Box developer console and set it to use the OAuth authentication method
2. In the configuration settings of your Box application, you will need to set the redirect URI to be https://id.atlassian.com/outboundAuth/finish
3. Finally, you will also need to add an entry to the CORS Domains containing https://*.cdn.prod.atlassian-dev.net

Before moving on you will want to make note of your Box application’s “Client ID” and “Client Secret” since they will be used in the next section. Along with any scopes your application’s functionality might require. For example: “Read all files and folders stored in Box”.

Forge Manifest

For this section you will need to have a Forge application and be able to edit the manifest.yml file. For more info on creating a Forge application you can review the getting started guide from the Forge developer documentation.

1. First you will want to setup your remotes for the Box API & Box Account base URLs to be these values
2. Next you will need to setup your permissions to allow your Forge backend to fetch the Box remotes
3. Once your remotes and permissions are done, you can setup the box provider basics from this template and copy paste your Client ID from the Box Developer Console where needed
4. Finally, you will need to configure the client secret using the Forge CLI with the value copied from the Box Developer Console

Fetching data from the Box API in Forge resolver functions

Once your Forge application is fully configured, you can start sending requests to perform actions against the Box API from a user’s context. Here you will find a sample setup of resolver functions that handle authentication, fetching account information, and fetching a user’s root folder.

Notice how each function’s first action is to get the box provider by performing asUser().withProvider(‘box’, ‘box-api’). This will give you back the box provider, and it will be pre-supplied with a user’s authentication if they have gone through the OAuth loop.

To perform this OAuth loop on the frontend, we simply invoke the ‘authenticate’ function via the Forge bridge immediately upon entering the application (or possibly when a user clicks a login button). Once the user has gone through the authentication process, the rest of the resolver functions above can be invoked on the frontend and will return their corresponding data for you to use.

Full OAuth flow in action

Now that the Forge application backend is fully setup and configured, we simply need a front-end to invoke the OAuth flow and fetch data once the user is authenticated. Here you will find a simple front-end setup (just two components) showing this off.

The app component above simply invokes the “authenticate” Forge function. If the user hasn’t authenticated yet, the Atlassian OAuth system flow will take over. If the user has authenticated, then the dashboard component here will be rendered.

Wrap-up

The Forge OAuth provider system streamlines a lot of the tedious, manual systems you would typically have to go through as a developer. It also provides enhanced security around your secrets and tokens, disallowing you from accidentally abusing them. This makes it perfect for any normal use-cases where you might need to setup OAuth in your Forge application to interact with a third-party API.

It should be mentioned though that with the Box API many folks will want to make use of Box’s UI Elements, which can give a Box-like look and feel to your application’s UI. Unfortunately, the UI Elements from Box require you to pass in a JWT token at runtime. Due to the heightened security that Forge has, you are unable to get the user’s OAuth token on the frontend in order to be passed into the Box UI Elements. Thus, you would need to recreate the elements yourself or make use of an alternative approach. You can read more about Box’s UI Elements and how authentication works with them here.