Skip to main content
When a user signs in to a custom Box application for the first time using their SSO provider credentials a new Box user will need to be created and associated with their SSO user record using some piece of unique information from that SSO user record. Typically the data that is used to make the association between those two accounts is either a unique ID or an email address. To make that association, a Box account may be created in a few ways:
  • Using the external_app_user_id field of a Box user to store the unique ID from the SSO provider.
  • Using the login field of a Box user to store the unique email from the SSO provider (managed users only).

​
Create association with external_app_user_id

Using the external_app_user_id field of a Box user record is a viable option for both app users and managed users, and is the recommended method when associating a user record from an SSO provider with a Box user account.

​
App user

To create a new Box app user with an external_app_user_id association to a SSO user record you will need two pieces of information from the SSO provider:
  • UID (required): The unique identifier from the SSO user record.
  • Name (optional): To maintain uniformity between the records, the SSO user name may be extracted to associate with the Box user record.
Once available, make a request to create a new app user, supplying the optional external_app_user_id definition in the user parameters. 
const ssoName = 'SSO User Name';
const ssoUID = 'SSO User Unique ID';
const spaceAmount = 1073741824;

// Create app user
client.enterprise.addAppUser(
    ssoName,
    {
      space_amount: spaceAmount,
      external_app_user_id: ssoUID
    }
).then(appUser => {
    console.log(`New user created: ${appUser.name}`);
});

​
Managed user

To create a new Box managed user with an external_app_user_id association to a SSO user record you will need two pieces of information from the SSO provider:
  • Email (required): The unique email from the SSO user record.
  • Name (optional): To maintain uniformity between the records, the SSO user may be extracted to associate with the Box user record.
Once available, make a request to create a new managed user, supplying the SSO user record email address for the login. 
const ssoName = 'SSO User Name';
const ssoEmail = 'ssouser@email.com';
const spaceAmount = 1073741824;

// Create app user
client.enterprise.addUser(
    ssoEmail,
    ssoName,
    {
        space_amount: spaceAmount
    }
).then(managedUser => {
    console.log(`New user created: ${managedUser.name}`);
});

​
Create association by email

Creating a new managed user that is associated by the SSO user email address is the same process as creating a standard managed user. After the user logs in via your SSO provider, if the user doesn’t already exist as a Box user, extract the email address from the SSO user record and make a request to create a new Box managed user. 
curl -i -X POST "https://api.box.com/2.0/users" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "login": "ceo@example.com",
       "name": "Aaron Levie"
     }'