Introducing Token Exchange for Box Platform
At Box, we’re always looking for new ways to help developers build secure, performant content applications in the cloud that leverage Box Platform APIs. That’s why today, we’re introducing a new capability of the /token endpoint of the Box Content API that allows developers to exchange higher-scoped tokens for more granularly-scoped tokens with a mechanism called Token Exchange. Token Exchange was designed to support the Box UI Elements, which require an access token to be passed to the client in order to be initialized.
To better understand access tokens with Box and Token Exchange, you can read the post below or explore our documentation.
What is Token Exchange?
When building with the Box Platform APIs, you have a few different options for how you can handle authentication depending on your application’s use case. But, no matter what authentication method you choose, you eventually need to retrieve an access token to include in the header of any API request you make to our APIs. When creating an application with Box, you can select the scopes of your application’s access token in the Configuration page of the Box Developer Console, granting your application as many permissions as you’d like depending on your application’s needs. These access tokens are ideal for making API requests from your server to Box’s servers.
That said, there are times where you might want to make specific API requests from the client for various reasons. For example, let’s say you’re building an app where an end user needs to upload a file and preview it in the application (like uploading and proofing a PDF resume in a recruiting portal). Once the file is uploaded into your application, there may be other activity around that file, such as a collaborative review process by various company employees, but the majority of your users will be external candidates simply uploading and viewing their resumes. In this case, it would make sense to allow the client to perform these operations for performance reasons, rather than proxying traffic to your server. Moreover, since this is a very transactional interaction, there’s no need to create new user accounts for every single job applicant, and so it makes sense to send these requests directly from the client.
To do this, you’d could pass your Service Account’s access token down to the client. While this would allow the client to perform the necessary operations, it would expose a fully-scoped access token on the client, which creates a security vulnerability. A technology-savvy end user could potentially gain access to all of the content in your application (depending on how you’ve configured your application’s permissions).
Instead, what if you could obtain a token that you could pass to the client that could only upload and preview files and nothing else? Well, this is exactly what you can do with Token Exchange.
With Token Exchange, you can take a higher-scoped token (known as the “parent” token) and scope it down to a token with the desired set of permissions (the “downscoped” token”). The downscoped token contains a subset of permissions on the parent token, and can be used to make requests on a particular resource, such as a file or folder. Using the downscoped token and the resource ID (a file ID, for example), you can make API calls directly to Box without the risk of exposing a fully-scoped token.
Now, using our downscoped token, the client can upload and preview files without passing a fully-scoped token to the client or having to obtain a user access token. Users have a seamless, performant experience and your application stays secure.
How do I use Token Exchange?
Using Token Exchange is fairly straightforward. Once you have created an application in the Box Developer Console, selected your authentication method, and obtained an access token (the parent token), you can use that parent token to request a downscoped token with a simple POST request to the /token endpoint of the Box Content API. In the request, you specify the subject token (your parent token) and the subset of scopes you want to be available in the downscoped token. It’s important to note that you can only request a subset of scopes that your parent token has. You can also specific a resource in your request to further restrict the token to only have permissions on a specific file or folder.
Your request might look something like this:
curl https://api.box.com/oauth2/token \-d ‘subject_token=<YOUR PARENT TOKEN>’ \-d ‘subject_token_type=urn:ietf:params:oauth:token-type:access_token’ \-d ‘scope=item_upload item_preview’ \-d ‘resource=https://api.box.com/2.0/files/5391641209' \-d ‘grant_type=urn:ietf:params:oauth:grant-type:token-exchange’ \-X POST
The Box Content API will then respond with a downscoped access token, which can then be used to make API calls from the client. Here’s what a response might look like:
{“access_token”: “1!OhzmV1rtsxHwyLIlaooRQII470kDPC_1UZ-77oZosPSV55lxPThEl3PfsIqdmUoLu9z8cb3MvIWIhmfr7c7VsTQhZhBJLgG7fDhjtdK8wlq0wtPHlyBXqQf2pMLK1cWegkI2Fj4ECqYBO-mCPMQ2UyWmlBXY_jVusczOqG1AorkRejsKEjblDd0sW-7scFPjQlaVw1qGmoADp5Z7Q2n3lBzZtPMfJb334wCVmSfjt_iQIByFVJpR3Vuq4ICkQGt0M1ly7tdfafr6CAcNT5lPN_DHa7k_ZtsbQQSiO4ZE6bIVa2fZnlVmBjFohqnT_Ahpl-kbHngYT8ISGkIEgXGduxH5KVRg6QTVdlH8bXBjinj3GHwi2KOiTDCp5i75pzeffUE77Sfy97YCN2EvcdqcblSnd_pvCBBGIjtuM_K4HkTk0SC5sZg_9EhJayPEOg82”,“expires_in”: 3964,“token_type”: “bearer”,“restricted_to”: [{“scope”: “item_preview”,“object”: {“type”: “file”,“id”: “5391641209”,“file_version”: {“type”: “file_version”,“id”: “619573369”,“sha1”: “c85ef6489c090ff71cda537bfbac47f1df721bba”},“sequence_id”: “0”,“etag”: “0”,“sha1”: “c85ef6489c090ff71cda537bfbac47f1df721bba”,“name”: “finland.JPG”}},{“scope”: “item_upload”,“object”: {“type”: “file”,“id”: “5391641209”,“file_version”: {“type”: “file_version”,“id”: “619573369”,“sha1”: “c85ef6489c090ff71cda537bfbac47f1df721bba”},“sequence_id”: “0”,“etag”: “0”,“sha1”: “c85ef6489c090ff71cda537bfbac47f1df721bba”,“name”: “finland.JPG”}}],“issued_token_type”: “urn:ietf:params:oauth:token-type:access_token”}
Token Exchange opens up a number of new ways you can utilize the Box Platform APIs in your applications. I encourage you to explore how to use token exchange in our documentation. If you have any questions, feel free to post in the Box Developer Forum or reach out to us via Twitter. We can’t wait to see what you build!
