Let’s talk about Box app users
I talk to a lot of customers who want to start using or expand use of Box for secure and easy collaboration with external users like partners, vendors, customers and contractors. Some are very happy to use Box ‘out of the box’ but others already have a significant investment in a custom experience for these users or a desire to provide it, and don’t want to introduce a separate app with yet another login for their users.
With the Box Platform app user concept we can provide the full scale of Box Content capabilities seamlessly and without the user having to login to Box (or even be aware that Box is the content layer!). This means that you can ‘bring your own tech’ when it comes to digital experience, web-site management and identity management and Box will seamlessly integrate.
After reading this article you should come away with a good understanding of what app users are, how they can be used, how to manage identity mapping, how and when to create app users and how applications that utilize app users can be architected.
So how does it work…
An app user is a Box user that can only access Box via the API. That means you are in full control over how and where content is surfaced to your end users, and by using app users you make sure that you can easily control and monitor content permissions and actions on a user level and have full auditability on actions taken by those users. So in terms of access to the capabilities of Box there is no difference between a traditional ‘managed user’ who can access box.com with a login and an app user. The difference is only how they each access (and how they are licensed, but more about this towards the end of the article).
A great example would be a vendor or customer portal where secure content collaboration is needed between a set of internal users and a larger and more fluid population of external users whose access is via a custom branded portal. You can find a portal example that has app users in this sample code repository. Below is also an architecture diagram of a portal deployment.
Since app users can only access Box via API you will need to either build the experience or integrate the Box API into an existing experience such as a website, mobile app or line of business application and use it to power the content experience part of the solution.
Identity
Some customers already have an identity management system in use, some will need to choose one but Box app users can work with pretty much any type of identity management system. To integrate Box app users with these, the approach is to create a unique mapping between the user in the identity system (think AD, Okta, Auth0, Ping and similar) and the Box app user. So when the application has established and confirmed the identity of the user, the interaction with the Box API as the app user can be established as well.
The mapping can be as shown below using the ‘external_app_user_id’ attribute on the Box user object to map to the unique user id in the identity management system. This is useful for situations where it is not possible or meaningful to change the user model in the underlying identity management system to reflect the mapping.
Alternatively the unique Box user id can be saved in a custom attribute on the user object in the identity management system as shown below.
Often customers will actually map the attributes both ways to make sure that the link between the users can be established regardless of where the application logic reads from first. In some situations the second option can be viewed as the best because it eliminates one extra API call to find the correct user in Box as the actual ID is already known.
Considerations for creating app users
Box App users can only be created via Box API and there are different approaches to when to create them:
- Pre-creation. This is useful if there is an existing process by which users are created in the identity management system. This could be a batch process or as part of an onboarding process where scripting could be used. Box CLI and the Box SDKs are great tools for these types of processes.
- Creation on registration. This covers scenarios where users can self-register to a service that has Box as a content layer or where there are different distributed services that can create users. As part of the user creation process a Box app user is created and granted the appropriate rights and permissions.
- Lazy/just-in-time creation. This is useful where only a subset of users actually need to access and interact with the content stored in Box. Instead of creating a Box app users for all users upfront, you wait until the user makes a choice to access content for the first time and create the app user then. Subsequent requests for content will then use the created user.
Providing access to content
As part of creating the app user it is a common requirement to provide access to certain content or add the user to specific groups for access. This can all be done via API once the user has been created and will often follow the business logic of the parent application. Eg. creating a shared folder between customer and advisor for a banking vault solution or giving the user access to certain case folders in case management system. Box has a well-defined and granular security model for this purpose.
Application design
A common pattern we see customers use is a model where external users (customers, partners, vendors etc.) access content via a custom portal experience using app users to connect them to Box. This portal could have information from other systems as well and can be branded accordingly. Internal users in this pattern are using Box as their regular content management platform but can also have secure collaboration with the portal users. Using Box UI elements for the portal UI is a great way to speed up development of the content part of the portal. Check out this react example for more details
Another pattern frequently adopted by customers use a model whereby all users, both internal and external, access content via a custom application experience and are represented by app users. This works well in situations where the same parent application is used by both internal and external users and box can integrate into this.
Backend uses of app users
So far I have focussed on how app users are used to represent external users such as partners, contractors and customers in different direct user experiences. But app users are also frequently used for backend processes that link Box to other systems or to solve some specific requirements within Box. They are well suited for this as they do not have to represent a specific user and as nobody can login to a user interface as the app user, the threat surface and potential for human error is greatly reduced. App users can be used as content owners where eg. separate ownership is required due to content being stored in Box Zones or to horizontally scale bulk processes that otherwise could run into Box API user based rate limits.
Quick word on licensing
It is important to note that app users are licensed differently than what we normally refer to as ‘managed users’ — users that can login to box.com via web, mobile or desktop. App users are licensed on a consumption model which means you only pay for active users and their API consumption (measured monthly) as opposed to ‘managed users’ which are licensed on a traditional seat model. For customers this means that using an app user model is good for scaling up to serve very large user populations where only a percentage of users interact with content on a monthly basis.
How to get started.
Have a look at the user models guide and the user types. Create your first app user with our API. Also check out this easy to follow Okta sample that integrates Okta identity management with Box Platform app users. For further reading here are links to working demos for Auth0, AzureB2C, AWS Cognito and Okta each mapping a user to a Box app user, showing diagrams for login and registration and each have a link to a GitHub repository.
…And as always, feel free to post questions on our developer forum.
