Going Beyond OAuth2: BYOD in the Enterprise

The second version of the Box API is an exciting step forward towards making it easier for app developers to store and retrieve their business content on Box programmatically. We created it so that you can surface Box as a content layer in your application and build around it in fun and innovative ways.

Box's API uses the OAuth 2.0 protocol for simple, but effective authentication and authorization. OAuth 2.0 is more developer friendly than previous schemes; developers can start using the Box API almost immediately.

For e.g., if you used Box's old authentication system with the API V2, you would send an auth token the following way:

Authorization: BoxAuth api_key=YOUR_API_KEY&auth_token=YOUR_AUTH_TOKEN

With OAuth2, your app communicates credentials to Box in the following way:

Authorization: Bearer YOUR_OAUTH2_ACCESS_TOKEN

BYOD and OAuth2

While iOS, Android and the recently launched Windows 8 provide great choice for consumers; it sends chills up the spines of IT when these same consumers bring these devices into their workplace to access corporate data. This phenomenon, called BYOD is a real concern for enterprise IT that would like to protect corporate data and be able to manage devices. If not regulated properly, enterprise adoption of the world's most popular consumer devices could turn into a nightmare.

With the disappearance of the traditional "office" and enterprises encouraging mobility, a significant chunk of access happens through mobile apps. These apps use Box’s new REST API as the underlying interface to interact with data on Box. Unfortunately, when it comes to accessing data through the API, the OAuth2 specification has no inherent capability for extending and revoking privileges to specific devices.

Box has always focused on simple sharing backed by strong security features. To solve the BYOD problem, Box’s API goes above and beyond the OAuth 2.0 specification to provide stronger security. To quote section 3.2.1 of the OAuth2 specification,

3.2.1.  Client Authentication

Confidential clients or other clients issued client credentials MUST authenticate with the authorization server as described in Section 2.3 when making requests to the token endpoint.

Box extends the standard OAuth2 specification so that we verify not only the identity of the client, but the identity of the device making the request as well.

Box's OAuth2 authorization server enhances OAuth2 authorization model so that if an enterprise has trusted access enabled, the bearer token can only be generated from an enterprise-authorized device. If this token is used from another device that  is not authorized to access corporate data (for e.g., the user's shiny new Android phone), the OAuth2 authorization endpoint blocks the request.

In order to connect an access token to a specific device, the client makes a request to the token endpoint by sending an extra parameter called ‘device_id’ using the “application/x-www-form-urlencoded” format with a character encoding of UTF-8 in the HTTP request entity-body. An example request in cURL for the authorization code grant looks like:

curl https://api.box.com/oauth2/token -d 'grant_type=authorization_code&code={your_code}&client_id={your_client_id}&client_secret={your_client_secret}&device_id={authorized_device_id}&device_name={human_readable_device_name}' -X POST

If you are using a refresh token to get a new access token, the refresh token grant also supports sending the device id as follows:

curl https://api.box.com/oauth2/token -d 'grant_type=refresh_token&refresh_token={valid refresh token}&client_id={your_client_id}&client_secret={your_client_secret}&device_id={authorized_device_id}&device_name={human_readable_device_name}' -X POST

Device id is an optional client specific alphanumeric string that should remain constant for the lifetime of the device. This string could be the (now deprecated) CFUUIDCreate library method in iOS. An alternative is to use the BPXLUUIDHandler project on GitHub. For Android, Settings.Secure#ANDROID_ID can be used. The device id can be leveraged to restrict corporate data access of other devices such as laptops, as long as the device id does not change. An app can choose to leverage this functionality for improved security, especially in a device pinning enabled enterprise.

Device name is an optional parameter that can be used by enterprise admins to visually identify devices that currently have access to enterprise data.

Let us assume that an enterprise has authorized a device with id '123' access to access its data. All other OAuth2 query parameters being valid, here is how device id is consumed by Box's OAuth2 authorization server for an enterprise that has enabled device pinning:

Incoming device id Is token request successful?
120 No
Device id missing No
123 Yes

You might wonder why Box does not check for a device id when at the OAuth2 authorization endpoint . The reason for this is that a device that was authorized when an authorization code was issued to it may be unauthorized (due to an enterprise admin invalidating the device) when it requests an access token. Hence it is more secure to check for device identity at the tokens endpoint.

To experience more exciting stuff in API v2, visit http://developers.box.com/docs/