When any actions happen in a Box account, they are automatically logged so that an admin or IT is never out of the loop with what is happening in their enterprise environment. From a product perspective, Box allows admins to run reports on a number of different vectors to check for specific user actions, see what apps are being used, or see if there are any suspicious events.
While this may be sufficient for some users, many will look to ingest these events into third-party Partner solutions, often connected to multiple other services or SaaS applications to have a single pane view into what is taking place in their suite of deployed applications. To facilitate this type of flow, Box has an API endpoint that can deliver all of the events happening through a JSON payload that can be ingested and analyzed by third party solutions.
This is called the Box Enterprise Event Stream and it gives you the ability to use a single endpoint to capture information about all of the users in the enterprise from a single endpoint. Note that while Box also provides a User Event Stream that is separate, it will only provide events from the perspective of the user token. For enterprise wide integrations, we will be looking specifically at the Enterprise Event Stream in this article.
The endpoint delivers a large number of event types that capture anything from a user uploading a file to potential security issues like file retention being removed.
When you are looking to integrate with this endpoint, note that Box provides two different options for the type of stream, one of which may be more beneficial depending on your use case. We have a great comparisons of the two steam types admin_logs and admin_logs_streaming that can be found in our developer documentation.
When looking to integrate with this endpoint, you will need a minimum set of permissions from both your application perspective and potentially from the user perspective based on the authentication type that your application uses.
Application Permissions
-
If you are using a JWT based authentication mechanism, you will need to make sure that your application is set up with the following settings:
- App Access Level: App + Enterprise Access - you will be capturing events across the whole enterprise.
- Application Scopes: these are the minimum permissions required to utilize the Enterprise Event stream to capture user actions.
- Manage Enterprise Properties
-
For OAuth 2.0 based authentication you will need to have the following settings:
-
Application Scopes - these are the minimum permissions required to utilize the Enterprise Event stream to capture user actions.
- Manage Enterprise Properties
-
User Permissions
-
For JWT based applications, there is a user that is automatically created during authentication that will mirror your application scopes, so no further work is required.
-
For OAuth 2.0 based application, you need to make sure that the main Admin of the Box enterprise authenticates into the application, or in some cases, you may want to have a dedicated Co-Admin level service account for your application. Since Box will take the lower of the permission sets between the Application Scopes and the Co-Admin scopes, the following permissions would need to be enabled
-
Reports and Settings: Run new reports and access existing reports
Note that these are the very minimum permissions needed to capture events from the Enterprise Event stream, if your application plans on doing any remediation steps, capture user information, etc. you may need to include additional scopes. You can learn more about the different scopes here
Integration flow, generally speaking, will look like the following:
-
Authorization: connection is established between your application and the Box enterprise either through an OAuth process or the Admin adding your JWT application API key in the Apps section
-
Get Enterprise Events: depending on whether you are doing a historical scan or like to have the most up to date information delivered as quickly as possible, you may want to use either the “admin_logs” or “admin_logs_streaming” event type.
-
Repeat: If you’re doing a historical scan, you can keep paginating through events until you are at the current date.
After you are caught up in real-time, you can choose an interval at which you would like to scan for new events in these endpoints and ingest the event information into your systems. Depending on if you’re looking for specific event types, using the “event_type” filter can greatly reduce the number of events that are being returned to you for processing. This will give you a more targeted approach, which can potentially be customized by the end user in your application by letting them choose which types of events they are looking to ingest from Box into your application.