There are a few different types of authentication methods available depending on the application type and one may suit your user experience better than others. In this article, we’ll cover the two most common ones — 3-Legged OAuth flow and OAuth with JWT — as well as some others options that are available to you – Web App Integration token exchange, Skills token delivery, and Box View static tokens. Different authentication options available may vary depending on the application type you chose during the application creation process, so you may see only some of the authentication types that we cover in this article.
Quick Reference:
- User Authentication (OAuth 2.0)
- Server Authentication (with JWT)
- Server Authentication (Client Credentials Grant)
- Limited Access App / App Token Auth
- Box Custom Skill
User Authentication (OAuth 2.0)
This is our most widely utilized authentication flow across many different partners. Generally, this flow requires an explicit agreement from each end user after they review the scopes being requested to grant the application access to their user and content.
There is a requirement with this authentication type – your app must have a publicly accessible redirect URI that you will need to set up during the application configuration which is utilized during the authorization process.
The overall flow of this authentication type is as follows:
-
User is sent to an authorization endpoint and asked to log in if they do not currently have an active session with Box
-
Box user is shown the different scopes that your application is requesting permission to and can choose to grant access
-
Once the user grants access, a security code is sent to your redirect URI that you set up in your application configuration
-
Your application will need to exchange the code for an access token and a refresh token that you can utilize to make API calls and to keep the tokens live respectively
This authentication type may require each user to explicitly grant access to your application and since the access token is only valid for about an hour (standard across most of our tokens), you need to keep track of the refresh token to be able to get new token pairs on demand.
Note that since this application requires users to authenticate in with an email and password, it will only work with user types that follow this authentication method. App users, for example, would not be able to utilize this authentication flow.
Server Authentication (with JWT)
This authentication type is similar to utilizing the User Authentication type described above, but provides a programmatic way to retrieve tokens without the users having to explicitly interact with the application. The main difference from an admin perspective is that they explicitly authorize this application for their whole enterprise with whatever scopes are chosen and then, the application is able to generate tokens from any of the user perspectives (if needed) without the individual users granting access.
When an admin authorizes this application, a user is created with elevated permissions based on the scopes that your application requested that acts as a service account for this application. Their default name is the name of your application and their email will follow the pattern of, “AutomationUser_YourServiceId_RandomHash@boxdevedition.com” with each enterprise that authorizes the application, generating a unique service account.
Rather than utilizing a redirect URI and you storing your application client secret as with the authentication type above, in this case, there is a public/private key pair that allows Box to identify you as the owner of the application. When requesting a token, you will send us (Box) an encrypted payload, we’ll check it, and send you back the token. The token itself is valid for about an hour for that user. In this case, there is no refresh token as retrieving a new token can be done by just sending us the encrypted payload again.
There are two different token types that you can request — if you specify a box_sub_type “enterprise” then you will be creating a token from the perspective of the service account (described above) that may have some admin-level only permissions. For example, if you want to create new users in the enterprise, this is the token type you would use. In the case of any other user, you would specify a box_sub_type of user and generate a token from that perspective, inheriting all of their permissions and access, but nothing outside of that — consider it as if you logged into that account on the web application, if they are not able to see or do something from the web application, they will have the same limitations through the API.
Server Authentication (Client Credentials Grant)
This authentication type is very similar in functionality to the JWT authentication type above, but simplifies the overall process of retrieving tokens. With the additional simplicity there may also be some security considerations that partners may want to consider.
The overall token retrieval process involves sending a POST request with your client id, client secret, and the type of token that you are requesting. In this case, the client secret acts as the main secure piece of data, so there is a bit less security when compared to the other auth models. This is often utilized for some on-prem, automation solutions, often built by in-house developers rather than for largely distributed partner applications.
The rest of the flows are very similar to JWT, where you have a service account, can generate tokens on demand for it or any other user in the enterprise, and perform actions based on the scopes that your application has requested as well as the permissions of the user token.
Limited Access App / App Token Auth
This application type has one of the most restricted use cases, but also one of the simplest authentication methods. The application type itself is meant largely for applications where the only use case is the previewing of files without any consideration of file/folder hierarchy or direct access through the Box web application. This serves the purpose of allowing distributed uploading of files, and then providing conversion services resulting in file previews that can be viewed in a browser.
With this credential type, after an admin authorizes the client id in their application console, you have a non-rotating access token that you utilize to upload content to Box, create preview sessions, and delete content. You have control over how long that token is valid for and can revoke it at any point, but if that token is exposed, then the content the account stores may also be exposed. This method requires very careful consideration and security posture when choosing to use this authentication type if the limited functionality is sufficient for your Box use case.
Box Custom Skill
This is a very specific token delivery method, largely meant to facilitate ML use cases to extract context around unstructured content. You can read more about the intended functionality of Skills on our developer website.
Purely from an authentication perspective, this application type is unique compared to the other ones. Instead of you requesting a token, in this case, we will push you a token along with a file information payload for you to be able scan the content.
When an event is triggered (in majority of cases a new file upload) we will send you the information that this file was uploaded and provide two tokens — one can be utilized to download the file and the other one is utilized for adding metadata back to the file itself. They are highly targeted, downscoped tokens, so you would not be able to touch any other content as this method is only meant to facilitate this flow.
If any further actions are required, you might consider using something like our Webhook v2 framework in addition to one of the authentication methods above, which would allow you to expand what you are able to do and what actions you want to be notified of moving forward. More on Webhooks can be found in our developer documentation.
For any questions, please contact our Partners team at integrate@box.com