Skip to main content
This topic explains how to set up and configure single sign-on (SSO) in Box for your organization.

​
Single Sign-On Overview

Single sign-on (SSO) is a method for authenticating users where a single set of credentials can be used to log into several different applications. With SSO, you use one password to access all of your applications, which reduces password fatigue and tickets to your help desk. This is especially useful in a corporate setting, when you want your employees to be able to access a variety of applications using their company credentials.

​
Box Support of SSO

SSO authentication is available in Business and Enterprise accounts. Box supports SSO via SAML 2.0 and acts as a service provider (SP) for SSO. The client must implement a federation service to act as an identity provider (IdP). An IdP is a user management tool connected to your use store and allows an admin or co-admin to define access to enterprise applications. Federation can be accomplished through an in-house or third-party provider. Common third-party IdPs include:
  • ADFS 2.0/3.0
  • Google Cloud
  • Okta
  • OneLogin
Some IdPs (Okta, OneLogin, etc.) have various levels of integration to Box through the Box API, which means there may be additional functionality that can be utilized to bring the user store and Box accounts more in sync. Examples of this functionality include automatic account provisioning upon addition to the IdP (pre-provisioning), automatic account deprovisioning upon removal from the IdP, and groups being periodically synced between the user store and Box (push groups). Please reach out to your IdP to confirm if this functionality exists. A high level diagram of the SSO sign in process is shown below:
diagram-of-the-sso-sign-in-process
  1. The user clicks Continue on their company branded Box subdomain, such as mycompany.box.com.
  2. Box forwards the request to the IdP. The user will be redirected to the IdP login page.
  3. The user logs in using their company credentials.
  4. The user is validated against the user store.
  5. SAML assertion is sent back to Box. At a minimum, the SAML assertion response from the identity provider must contain the user’s email address. The email address must correspond to a user within that Box account. The user’s given name and surname attributes are typically sent as parameters as well, but they are not required to enable SSO.
  6. The user’s session is authenticated and they are logged into their Box account.
Note: SSO with Box is an authentication method, not an integration. There is no method to sync the individual accounts in a user store to the user accounts in Box.

​
Setting Up Single Sign-On

Prerequisites:
  • A Business or Enterprise Box account.
  • Primary administrator or a managed user with co-admin permissions and at least the following privileges in the Reports and Settings section selected:
    • View settings and apps for your company
    • Edit settings and apps for your company
Note: Account creation emails can only be set up by the primary admin. This option does not appear for co-admins.

​
Setting Up SSO On Your Own

Administrators and co-admins also have the option of setting up single sign-on on their own. If you’re comfortable modifying your enterprise’s security settings without Box’s assistance, setting up and enabling single sign-on for your enterprise is easy. It requires 3 steps:
  • Configure SSO
  • Test SSO
  • Require SSO
Note: Enabling SSO Test Mode means users will be able to sign in via SSO or by using their Box credentials. Once SSO Required is enabled, users are only able to log in via SSO.
To Configure Single Sign-On:
  1. Go to Admin Console > Enterprise Settings.
  2. Click the User Settings tab.
  3. In the Configure Single Sign-On (SSO) for All Users section, click Configure.
  4. Select your Identity Provider (IdP). If you don’t see your provider listed, use the Box SSO Setup Support Form to have Box help you set up SSO.
  5. Upload your IdP’s SSO metadata file. If you do not have a metadata file or if you need your metadata file updated, use the Box SSO Setup Support Form to have Box help you set up SSO.
  6. Click Submit.
A status indicator will appear in the Configure Single Sign-On (SSO) for All Users section to inform you of the SSO processing progress or if there were any errors.
Note: If your IdP isn’t supported by Self-Service SSO, an error will appear in the Configure Single Sign-On (SSO) for All Users section. If you need to update your SSO configuration in this case, please contact Box Product Support.
Once the file has been processed successfully, Box sends a notification to the email address of the main account admin and co-admin. This time is a good opportunity to notify your enterprise of the new login process. To enable Single Sign-On Test Mode:
  1. Go to Admin Console > Enterprise Settings.
  2. Click the User Settings tab.
  3. In the Enable Single Sign-On (SSO) for All Users section, enable SSO Test Mode.
To enable Single Sign-On Required:
Important
  • For security reasons, enabling SSO Required is considered a “critical action” and requires multi-factor authentication (MFA) to complete.
  • Be sure you have tested the SSO login flow before enabling this setting. If you do not test that your SSO credentials are working correctly, you could be locked out of your Box account.
At this point, all of your managed users should be able to access Box via your chosen SSO provider. In addition, they will be unenrolled in MFA (if you had it enabled) because that is also handled by the SSO provider.
  1. Go to Admin Console > Enterprise Settings.
  2. Click the User Settings tab.
  3. In the Enable Single Sign-On (SSO) for All Users section, disable SSO Test Mode and enable SSO Required.
  4. In the Enable SSO Required dialog box, select both checkboxes, then click Enable for All Users.
  5. Use MFA to authenticate this change, using the method described in Multi-Factor Authentication Required for Admin Console Critical Actions.

​
Disabling Single Sign-On

Disable single sign-on by disabling the SSO Required toggle. For security reasons, disabling SSO is considered a “critical action” and requires multi-factor authentication (MFA) to complete.

​
Technical Details

Listed below are expected configuration file values for each IdP:

​
Okta

  • Okta Metadata File (metadata.xml)

​
ADFS

​
Entra ID

​
Google Cloud

  • firstnameAttribute = firstName
  • lastnameAttribute = lastName
  • emailAttribute = SAML_SUBJECT

​
OneLogin

  • firstnameAttribute = firstName
  • lastnameAttribute = lastName
  • emailAttribute = SAML_SUBJECT

​
Setting Up SSO through Box

sso-setup-process
Discover - After finalizing the IdP (identity provider) selection, fill out our Box SSO Setup Support Form. See the instructions on this page for the required information on the form. Set up- Upon receiving the SSO Setup Support request, a member from the Box technical team will set up the connection from our SP (service provider) to your IdP. Similarly on your side, you will need to set up the connection from your IdP to our SP using our metadata or info. Test - Turning on SSO Enabled in your Enterprise Settings will display the company-branded Box login page. You cannot modify or omit this branded page.
sso-login-flow
During the SSO Enabled phase, managed users can log in to Box.com using their company’s email address and password, or they can utilize their company’s login credentials through their Box subdomain. This setting is acceptable during testing, but for production should be changed to SSO Required. Deploy- Following testing, the Box instance should be transitioned to the SSO Required state so all managed users may only log in to Box using their company login credentials through their IdP login page. Any Box-created applications (such as Box Sync) will work using SSO. This is the preferred method because it forces use of SSO. If there is a subset of managed users that are not able to authenticate via SSO (contractors, vendors, etc.), SSO should not be required on the account.
Note:
  • FTP applications do NOT support SSO. Users will have the option to create external passwords if they need to use these applications.
  • The Admin Console setting that enables admins and co-admins to force password resets after a certain number of days only applies to users’ External Passwords. This setting does not affect SSO credentials.

​
IdP Requirements

  • Must support SP initiated SSO
  • Must support SAML 2.0

​
What you need from Box to set up your connection

OR

​
What Box needs from your identity provider

  • Entity ID, Connection ID, or External Key
  • Redirect URL
  • Public Certificate
OR
  • Metadata file containing all of the above information
Note: The Entity ID in an SSO configuration must be unique within Box. Using the same Entity ID across multiple Box environments (EIDs) will cause the setup to fail.To temporarily remove an SSO configuration so it can be applied to another environment, it must be removed on the Box side. To do so, open a ticket with Box Support. If you want users to sign in to multiple Box environments with the same SSO configuration, this can be enabled through paid Box Consulting; contact your account team.
More instructions on obtaining this information for the most common IdPs can be found below. These instructions may vary slightly for implementations, so you should check with your specific IdP if you have any issues. If you are not using one of the most common IdPs listed above, please also provide Box with the attribute names for email, first name, and last name (Ex: “email”, “firstName”, “lastName”).

ADFS 2.0/3.0

You will need your metadata xml file for SSO setup. To collect your ADFS metadata file:

  1. Go to the below link and download the xml file:
  2. Attach your metadata file to the Box SSO Setup Support Form or see our guide for Setting Up SSO on your own.
Help Article

Entra ID

You will need your metadata xml file for SSO setup. To collect your Entra ID metadata file:

  1. Go to the tenant portal by going to the following link: https://TENANTNAME/federationmetadata/2007-06/federationmetadata.xml
  2. Attach your metadata file to the Box SSO Setup Support Form or see our guide for Setting Up SSO on your own.
Help Link

Bitium

You will need your metadata xml file for SSO setup. To collect your Bitium metadata file:

  1. In Bitium, go to Manage Apps.
  2. Select Box from the list of installed apps.
  3. Click the Single Sign-On tab.
  4. Click the dropdown menu and select SAML authentication.
  5. Download the metadata XML file.
  6. Use this information to fill out the Box SSO Setup Support Form.
 

Entrust Identity

You will need your metadata xml file for SSO setup. To collect your Entrust Identity metadata file:

  1. In Identity as a Service, go to Resources > Applications.

  2. Click the download icon download-icon next to the application you are integrating with Identity as a Service.

  3. From the drop-down list, select the certificate to include in the SAML IDP Metadata file.
  4. If applicable, select the domain to include.
  5. Click Download.
Help Link

Google Cloud

You will need your metadata XML file for SSO setup. To collect your Google Cloud metadata file:

  1. With a super administrator account in the Google Admin Console Home page, go to Apps > Web and mobile apps.
  2. Click Add App > Add private SAML app.
  3. On the App Details page, enter the name of the custom app.
  4. Click  Continue.
  5. On the Google Identity Provider details page, get the setup information needed by the service provider using one of these options:
    • Download the IDP metadata.
    • Copy the SSO URL and Entity ID and download the Certificate (or SHA-256 fingerprint, if needed).
  6. Attach the Metadata XML file to the Box SSO Setup Support Form.
Help Link

Nopassword by WiActs

You will need your metadata XML file for SSO setup. To collect your NoPassword metadata file:

  1. Go to Nopassword Admin Dashboard > Apps.
  2. Go to the Add Application section, type “Box” and select Box from the drop-down menu.
  3. On the second page of App Setup wizard, click on the Metadata hyperlink to download it.
  4. Attach the Metadata XML file to the Box SSO Setup Support Form.
 

MobileIron

You will need your Metadata XML file for SSO setup. To collect your MobileIron Access metadata file:
 

  1. Go to your MobileIron Access Management Server
  2. Go to Profile > Federated Pairs > Select the federated pair for Box.
  3. Choose Access IDP Metadata (Upload to SP) > Download.
  4. Use this information to fill out the Box SSO Setup Support Form.
 

Okta

You will need the External Key, Redirect URL & Public Certificate for SSO setup. To collect the information:

  1. Go to your Okta Admin dashboard > Applications > Box.
  2. Go to Single Sign-On tab > SAML 2.0 > View setup instructions (Ignore default relay state).
  3. Copy the External Key and Redirect URL.
  4. Download the cert file.
  5. Use this information to fill out the Box SSO Setup Support Form or see our guide for Setting Up SSO on your own.
Setup Guide

OneLogin

You will need your metadata XML file for SSO setup. To collect your OneLogin metadata file:

  1. Go to your OneLogin Admin dashboard > Company Apps > Box.
  2. Go to SSO tab > Single Sign On.
  3. Go to the Issuer URL > Download the metadata.
  4. Use this information to fill out the Box SSO Setup Support Form or see our guide for Setting Up SSO on your own.
Setup Guide

PingIdentity

You will need your metadata XML file for SSO setup. The XML file must contain the following metadata:

  • Entity ID, Connection ID, or External Key
  • Redirect URL
  • Public Certificate

To collect your PingIdentity metadata file:

  1. In the PingFederate administrative console, open the Metadata Export window.
    • For PingFederate 10.1 or later: go to System > Protocol Metadata > Metadata Export.
    • For PingFederate 10.0 or earlier: go to System > Metadata Export.
  2. Select the metadata to include in the XML file.
  3. Export the file.
  4. Use this information to fill out the Box SSO Setup Support Form or see our guide for Setting Up SSO on your own.

For additional details, see the Exporting SAML metadata from PingFederate topic in the PingIdentity documentation.

 

Other/Custom IdPs

Contact your IdP directly to assist in obtaining metadata file OR entity id, redirect URL, and signing certificate. Once obtained, use this information to fill out the Box SSO Setup Support Form. 
Info: SSO works also for the Box Drive app. See Using Box Drive Basics for more information.

​
SSO Account Settings

​
Account Creation Emails

When SSO Required is turned on, you also have the ability to suppress account creation emails. To do this, navigate to Admin Console > Enterprise Settings > Notifications tab.
supress-sso-account-creation-emails
By default, your new account holders receive a “Welcome to Box” email asking them to set up a password. This can be confusing because they are now using their AD password, not their Box password, to log in to Box.
Note: This setting only appears for the primary admin. It cannot be changed by co-admins.

​
SSO Logout URL

By default, logging out from Box will bring users back to their company branded Box login page. However, because Box does not support Single Log-Out (SLO), the user will still be authenticated in the company IdP, and therefore, when they click the “Continue” button, they will be automatically directed back to their Box account without having to provide an email address and password. To remind users that logging out of Box does not log them out of their IdP session, the redirect URL for logging out from Box can be changed. Examples of possible URLs include the IdP homepage or the IdP logout page.

​
Setting a custom logout URL

Contact your Box Customer Success Manager, or Box Product Support, with the logout URL you want.

​
SSO on-the-Fly Registration (Auto-Provisioning)

Accounts can be provisioned automatically the first time a user logs in to Box. By validating a user, the IdP is communicating to Box that the user should be allowed to have an account. If a user should not have an account, the SAML assertion should not be sent to Box by imposing restrictions through the IdP such as security groups. These accounts will be created using the new user settings defined by the account admin or co-admin in the Admin Console (Admin Console > Enterprise Settings > User Settings tab > New User Defaults). To create these accounts, a first and last name must be sent over in the SAML assertion with the email. The account creation process is the only time the first and last name attributes in the SAML assertion are used.

​
Setting up SSO Auto-Provisioning:

Contact your Box Customer Success Manager, or Box Product Support with first and last name attributes for the SAML assertion.

​
Auto Enrollment

Auto enrollment prevents users from creating free Box accounts using their company’s email address:
message-that-users-can-t-create-free-box-accounts-with-company-email
To avoid user login failures caused by the absence of provisioned accounts, we strongly recommend you enable Auto Enrollment after enabling Auto-Provisioning. See Domain Auto Enrollment for information on how to enable Auto Enrollment.

​
Implementing Groups in Box via SSO

For accounts with SSO Enabled/Required, admins or co-admins can choose to have groups in their user store populated within Box. This is a one-way communication from the user store to Box via the SAML assertion. When users log in to Box using SSO, they can be added and removed from groups based on their groups within the user store and the settings chosen by the Box admin or co-admin. The SAML assertion requires an attribute to relay the group information. For existing SSO connections, this may require changes. The group information is sent in a multi-value attribute: 
<Attribute Name="http://schemas.xmlsoap.org/claims/Group">
  <AttributeValue>MyGroup4</AttributeValue>
  <AttributeValue>MyGroup3</AttributeValue>
  <AttributeValue>MyGroup2</AttributeValue>
  <AttributeValue>MyGroup1</AttributeValue>
</Attribute>
After the SSO Groups feature is enabled, a User Groups Settings section becomes visible in Admin Console > Enterprise Settings > User Settings:
user-groups-settings
For some IdPs, this section becomes visible automatically when you enable SSO:
  • If you are using Okta or Google Cloud for your SSO, the User Groups Settings section appears after you enable SSO for either of these iDPs and upload your metadata file.
  • If you are using OneLogin, ADFS (Active Directory), or any other IdP compatible with SAML Groups for your SSO, contact your support representative to enable the User Groups Settings section.
Here is a brief description of each setting:
  • Add new groups upon SSO user login – If a group is sent over with a user and there isn’t an exact name match to a group within Box, this group will be added as a new Box group. Permissions must be manually assigned to this group in the Admin Console. This setting can be used to bring the exact names of multiple groups under an admin account.
  • Add user to groups upon SSO user login – If a group is sent over in the login SAML assertion which matches the name of an existing Box group, the user will be added to that Box group. When this setting and the next setting (“Remove User”) are enabled, your user store’s group memberships will update the Box user’s group memberships upon every login.
  • Remove user from groups upon SSO user login – If the user is currently in an existing Box group and the group is not sent over in the login SAML assertion, the user will be removed from that Box group. When this setting and the previous setting (“Add User”) are enabled, your user store’s group memberships will update the Box user’s group memberships upon every login.
When all three SSO Groups options are enabled, your user store will be the system of truth for group creation and membership in Box.

​
Limitations

  • Nested groups are not supported. Group hierarchies must be collapsed. Please check with your IdP to confirm that group hierarchies can be collapsed if needed.
  • This is a one-way method (via SAML). Any changes to a group in Box will not be reflected in the user store. If changes are not implemented in the user store, a user’s group membership will be reverted to the original settings on the next login.
  • Group memberships are synced upon user login. If a user never logs out, the user’s group memberships may be out of date since a new SAML assertion will never be sent.
  • SSO can create and update a user’s group membership
  • Group permissions must be manually assigned via the Box web application or API.
In addition, Active Directory is limited to 100 groups. This restriction does not apply when groups are added through the API (for example Entra ID).

​
Adding email aliases to user accounts via SSO

For enterprise accounts with SSO enabled, the admin or co-admin can choose to have email aliases populated via SSO. The SAML assertion requires two separate attributes to relay the email address information. A single value attribute is used as an identifier to determine what account to log a user into. This attribute is also used to determine the primary email address that receives all email notifications. The email aliases are sent in a second multi-value attribute: 
<Attribute Name="primary_email">     <AttributeValue>primaryemail@box.com</AttributeValue> </Attribute> <Attribute Name="email_aliases">     <AttributeValue>alias1@box.com</AttributeValue>     <AttributeValue>alias2@box.com</AttributeValue>     <AttributeValue>alias3@box.com</AttributeValue> </Attribute>

​
Restrictions:

  • Email addresses can only be added if they are in a managed domain. To register more domains with your Box account, contact your Box representative.
  • An email address can only be associated with a single Box account.
  • Only aliases that are initially added with SSO can be removed with SSO.

​
SSO and Reverse Proxies

Due to security best practices, cross-origin requests during the SAML flow will cause the login attempt to fail. For example, if a user initiates the SAML flow on one URL format (i.e. https://sso.services.box.net), and then completes the SAML flow on a different URL format with a reverse proxy URL extension (i.e. https://sso.services.box.net.mcas-gov.us), the session validation cookie is lost due to the cross-origin request and the login is rejected. This most commonly occurs if a user is sent to a reverse proxy in the middle of the SAML flow. If you are affected by this scenario, please open a ticket with Box Product Support to discuss available solutions.

​
SSO and Changing User Email Addresses

Once SSO is enabled, users no longer have the ability to change the email addresses in their accounts. This is because the source-of-truth email address is maintained by the identity provider. See Changing an Email Address for a Single Sign-On Account for details. In addition, the Make primary option described in Manage Account Settings is not available for secondary/linked email addresses on the user’s Account Settings page.