Deprovision Users with the Box API or CLI

Introduction

Objective
The goal of this Guide is to walk you through the API calls needed to deprovision managed users in Box. The specific API calls you will need to make are outlined below.

Caveats
This Guide will not cover specifics on how to build the business logic within the script or application that will make the API calls. You can find helpful SDKs in several web programming languages on our Developer portal. 

 

Box Command Line Tool for Deprovisioning

If your use case is just a one-time deprovisioning of users and would prefer avoiding the setup process of SDK management, Box's Command Line Tool has functionality to deprovision users. Developers should feel comfortable working on the command line to use this application.

You can get started with Box's CLI tool by visiting the Getting Started documentation. 

If you decide to go with this option for deprovisioning users instead of using our SDKs, feel free to skip the Prerequisites section and jump straight into the Deprovisioning Process section.

 

Prerequisites

Create your App
Before you begin, please ensure that you have a Box app setup in the Box Developer portal. The Box Developers Getting Started Guide will help you through this process, or if you want to jump right into it you can go ahead and create an app.

Authentication
One of the biggest challenges developers can have when first using the Box API is authentication. Box uses OAuth 2.0 to authorize your app to perform actions in Box on behalf of a specific user. In this case, we will want this user to be any Admin (or Co-Admin) in your Box instance. The OAuth process can be challenging to grasp, so please reference our Authentication with OAuth guide before getting started. The output of the OAuth authentication process will be an Access Token and a Refresh Token, and the Access Token will be used in every API call you make to Box.

As-User Functionality
For certain steps below, your application will need the ability to perform API calls on behalf of managed users. This can be enabled in the configuration tab of the Box Developer Console. If you're using JWT auth please ensure you reauthorize your application and obtain a new token pair for the change to take effect.

Service Account
If you want to move users' content to another Box user before deletion, this user account will need to be created in Box before running this script. You will also need to know the Box user ID of this user, which can be found programmatically via a call to the Get Enterprise Users endpoint (or by working with your Box representative). 

Deprovisioning Process

There are several steps to deprovisioning a user in Box. These steps may be optional depending on how you want to manage the existing content owned by the user. Which steps are required will depend on how you want to handle this content. Below is an outline of all potential steps:

• Move User to Inactive Status
• This will immediately log the user out of all apps (Box Sync, Mobile, etc)
• Collaborators on folders owned by this user will not be able to access collaborated content while the user is inactive

You can find a detailed explanation of each step, including all API calls needed, in the sections below.

 

Box Command Line Usage for Deprovisioning Users

	Action	Command Line Entry	Notes
1.	List All Users in Box	$ box users	Add "--csv" flag to format. Add "-s" to save file.
2.	Migrate Content owned by a Single User	$ box users:transfer-content {USERID} {NEWUSERID}
3.	Migrate Content for bulk users in one action	$ box users:transfer-content --bulk-file-path='./example.csv'	Expected Input (Example): 546781,100001 This moves content from user "546781" to "100001"
4.	Delete Single User	$ box users:delete {USERID}
5.	Delete bulk users in one action	$ box users:delete --bulk-file-path='./example.csv'	Expected Input (Example): 546781 This deletes user with ID "546781"

 

Box SDK Usage for Deprovisioning Users

Get a List of All Users in Box

User deprovisioning requires that you inactivate AND/OR delete a user in Box. In order to know which Box users have been deactivated in Active Directory, you must compare the status of your Box users to the status of your Active Directory users. This step allows you to get a list of all users in Box, including their user ID and email address. You can use their email address to poll Active Directory and see if the user has been deactivated there. If so, you will wan to use the Box User ID in subsequent parts of this guide. All calls should be done from an Admin account!

	Action	API URL Endpoint (links to documentation)	Additional Notes
1.	Find the Box User ID for the user we want to act upon	GET /users	Request URL Parameters (optional) filter_term={email_address} Returns only the user object that matches the user in question Response: User object. Contains the login (email address) and user ID of the user in question.

Move Remaining Content to a Generic Service Account

Any remaining content left in the user's account (or all of it, if you haven't affected any content up to this point) can be moved to a generic service account. This will need to be an existing user in Box and you will need the user ID (see "Prerequisites" above). We also want to create a container folder to store all of the user's content in, to make it easy to find content previously owned by the folder in the future.

All calls should be done from an Admin account!

	Action	API URL Endpoint (links to documentation)	Additional Notes
1.	Move all of user's content to Service Account	PUT /users/{USER_ID}/folders/0 *where {USER_ID} is the Box ID of the user whose content is being moved (from the above step)	Request Body Parameters: owned_by: { id: <USER_ID of Service Account> } Response: Status code: 200 AND Folder object. Contains the folder ID of the newly created folder.
2.	Rename the folder to include user's email address (Optional)	PUT /folders/{FOLDER_ID}	Request Header: As-User: <USER_ID of Service Account> This is optional, depending on which user the application is authenticated against. Request Body Parameters: folder_id: <folder ID returned by previous call above> name: <new folder name of choice> Can include previous user's email address or another attribute for tracking purposes Response: Status code: 200. Indicates that folder's name has been updated correctly. If folder is not updated correctly, this folder should be flagged to be named manually.

Additional Information about newly created folder after move to Service Account

The new folder created by the Move Folders endpoint will have the following attributes:

Folder Name: [User's Name]’s Files and Folders

Folder Description: This folder contains files previously owned by [User's Name], and were transferred to you by your enterprise administrator. If you have any questions, please contact [Enterprise Administrator's Name and Email].

Delete or Downgrade the User
User deprovisioning requires that you inactivate AND/OR delete a user in Box. Inactivation is an optional first step if you will be deleting users programmatically, however it is the minimum required step if you will not be deleting users programatically. Inactivating a user will immediately log them out of all apps (Box Sync, Mobile, 3rd party apps, etc). It will also temporarily freeze all of a user's content. Collaborators on folders owned by this user will not be able to access collaborated content while the user is inactive. There, the inactive status should only be used temporarily as a "hold period" when you are deciding where the user's content should be moved to. All calls should be done from an Admin account!

	Action	API URL Endpoint (links to documentation)	Additional Notes
1.	Delete the user	DELETE /users/{USER_ID}	Request Body Parameters: notify: true/false Indicates whether or not to notify user via email about account deletion force: true Indicates whether or not to delete user even if user still owns content Response: Status code: 204. Indicates that the user has been successfully deleted.

	Action	API URL Endpoint (links to documentation)	Additional Notes
1.	Downgrade the user to a 'Lite' (free) account	PUT /users/{USER_ID}	Request Body Parameters: enterprise: null Moves the user's account outside of your Box Enterprise Response: Status code: 200. Indicates that the user has been successfully downgraded.

 

Additional Considerations

• You will need a method to determine which users the script should act upon.

• Will the script be triggered by a specific action? Or will it run periodically and check all users for deactivation in Active Directory?

• You will need a method to get the login (email address) or Box user ID of the user the script should act upon.