Find app user for SSO identity

When a user logs into a platform application with their SSO provider, the first step that should be taken is to see if that user already exists from a previous login attempt where a Box user record was already created. If a Box user is found you should , or make , to access Box APIs as that user. If a Box user is not found you should create a new user with an association to the SSO user record. To search for existing users the endpoint may be used. Depending on whether you’re using the external_app_user_id or login method your query will look slightly different. Choose the search method that matches how you originally associated the SSO identity to the Box user in :

Use external_app_user_id if you stored the SSO provider’s unique ID on the Box user. This works for both app users and managed users.
Use the login email if you created a managed user whose login is the SSO email address.

Find user by external app user ID

To search for enterprise users by the stored external_app_user_id value you will need one piece of information from the SSO provider:

UID (required): The unique identifier from the SSO user record.

Once available, make a request to the list enterprise users endpoint, supplying the external_app_user_id definition in the parameters.

You can retrieve app users for a specific application only if such app users were created by this application. If you use one application to search for users created by a different one, no data will be returned.

const ssoUID = 'SSO User Unique ID';

// Check enterprise users for matching external_app_user_id against SSO UID
client.enterprise.getUsers({ "external_app_user_id": ssoUID })
.then((users) => {
    if (users.total_count > 0) {
        // User found, fetch user ID
        const userId = users.entries[0].id;
    } else {
        // User not found - create new user record
    }
});

String ssoUID = "SSO User Unique ID";

// Check enterprise users for matching external_app_user_id against SSO UID
URL url = new URL("https://api.box.com/2.0/users?external_app_user_id=" + ssoUID);
BoxAPIRequest request = new BoxAPIRequest(client, url, "GET");
BoxJSONResponse jsonResponse = (BoxJSONResponse) request.send();
JsonObject jsonObj = jsonResponse.getJsonObject();
JsonValue totalCount = jsonObj.get("total_count");

if (totalCount.asInt() > 0) {
    // User found, fetch
    // Fetch user ID
    JsonArray entries = (JsonArray) jsonObj.get("entries");
    JsonObject userRecord = (JsonObject) entries.get(0);
    JsonValue userId = userRecord.get("id");
} else {
    // User not found - create new user record
}

sso_uid = 'SSO User Unique ID'

# Validate is user exists
url = f'https://api.box.com/2.0/users?external_app_user_id={sso_uid}'
headers = {'Authorization': 'Bearer ' + access_token}
response = requests.get(url, headers=headers)
user_info = response.json()

if (user_info['total_count'] == 0):
    # User not found - create new user record
else:
    # User found, fetch user ID
    user = user_info['entries'][0]
    user_id = user['id']

Find user by email address

To search for enterprise users by their login email you will need one piece of information from the SSO provider:

Email (required): The unique email from the SSO user record.

Once available, make a request to the list enterprise users endpoint, supplying the email address as the filter_term, which is made available to search by email or name.

const ssoEmail = 'ssouser@email.com';

client.enterprise.getUsers({filter_term: ssoEmail})
    .then(users => {
        if (users.total_count > 0) {
            // User found, fetch user ID
            const userId = users.entries[0].id;
        } else {
            // User not found - create new user record
        }
    });

String ssoEmail = "ssouser@email.com";

Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(client, ssoEmail);

sso_email = 'ssouser@email.com'

users = client.users(user_type='all', filter_term=ssoEmail)
if (users['total_count'] == 0):
    # User not found - create new user record
else:
    # User found, fetch user ID
    user = users['entries'][0]
    user_id = user['id']

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Find app user for SSO identity

Find user by external app user ID

Find user by email address

​Find user by external app user ID

​Find user by email address

Find user by external app user ID

Find user by email address