Setting Up Single Sign-On (SSO) for Your Organization

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:

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.

Setting Up Single Sign-On

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

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.

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.

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.

To enable single sign-on required:

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

• firstnameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• lastnameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
• emailAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Azure

• firstnameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
• lastnameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
• emailAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Google Cloud

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

OneLogin

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

Setting Up SSO through Box

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.

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 method is preferred 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. 

IdP Requirements

• Must support SP initiated SSO
• Must support SAML 2.0

What you need from Box to set up your connection

• Entity ID: box.net
• Security Token Consumer URL: https://sso.services.box.net/sp/ACS.saml2
• Public Certificate

OR

• Box Metadata File

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

More instructions on obtaining this information for the most common IdPs can be found below. These instructions may be vary slightly 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”).

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.

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. 

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:

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:

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 AzureAD).

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.

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.