Okta

This guide provides the steps required to configure Provisioning for Box and includes the following sections:


Features

The following features are supported:


Configuration Steps

Configure Provisioning for Box as follows:

  1. Under the Provisioning tab, click Configure API Integration.

  2. Check the Enable API Integration box.

  3. Box uses Oauth to integrate with its API, the integration uses the Box admin's credentials during setup to authorize Okta to perform actions on the Box admin's behalf.

  4. Once the authorization process is complete, select To App in the left panel, then select the Provisioning Features you want to enable:

    images/apps/boxprovisioning1.png


Create Users - Configuring Personal Box Folders

If you enable the Create Users feature, you need to make some further configurations:

When Okta provisions a new user account in Box, it will simultaneously create a Box folder if the Create person Box folder when new user account is provisioned option is selected.

  1. Owner of the Box Personal Folder: Either:

    • Admin as Owner (default). When this option is selected the owner of the folder is the Box admin that authenticated Okta to the Box API and is assigned to the newly provisioned user account at the chosen permission level (Editor, Co-Owner). For this option, you would also need to specify the Full path to parent folder where you want the folder to be created in your Box tenant, for example All Files/Parent Folder.

      box_new5.jpeg

    • User as Owner. When this option is selected, the owner of the folder will be the new user provisioned to Box. You do not to need to specify a folder path, as the folder will be created in the User's root directory. The advantage of this setting, is that it prevents the Box admin from being owner of large number of folders, thus preventing any errors caused by the admin being the owner of too many folders.

      box_new6.jpeg

  2. Personal folder name format:

    Both of the above methods of folder creation (Admin as Owner and User as Owner), allow you to create Personal Folder with a name based on the personal folder name format setting. By default this setting is set to use the Okta Username Prefix, but you can create custom expressions, with the help of Okta Expression Language.

    box_new7.jpeg

    box_new8.jpeg


Deactivate Users - Configuring Box Offboarding

If you enable the Deactive User feature, you need to make some further configurations:

  1. The default status upon deactivation is to make a user Inactive:

    “box1.png”

  2. To change to a different status upon deactivation, select the Deleted option from the Box user status on deactivation dropdown menu.

    Once you select the Deleted option, you need to specify the File management upon user deletion action:

    1. The first file management action once a user is deleted is to Transfer user’s files to account user. If you select this option, you need to enter a valid, active Box account in the text field to which a user's files will be transferred when they are deactivated:

      “box2.png”

    2. The second file management action once a user is deleted is Do not delete users with files, create manual de-provisioning task. If you select this option, only users with no files in their account will be deleted when deactivated through Okta. A task is also generated when deactivating a user with files requesting manual de-provisioning:

      “box3.png”

    3. The third file management action once a user is deleted is to Delete all files - are you sure?. Note that if you select this option, files will be permanently deleted from a user's account when they are deactivated:

      “box4.png”


Schema Discovery

This is an Early Access feature, contact Okta Support to enable it.

Box supports User's Schema Discovery, so you can add extra attributes if available to User's Profile. To do that in Okta:

  1. Navigate to Directory > Profile Editor.

  2. Select the APPS section in the left pane, then find your app in the list.

  3. Check the list of the attributes and if you didn't found what you need, click the Add Attribute to display the following list of extended attributes:

    • firstName
    • lastName
    • timezone
    • language
    • space_amount (RO)
    • max_upload_size (RO)
    • job_title, phone
    • address
    • avatar_url (RO)
    • groups
    • space_used (RO)
  4. Check the attributes you want to add, then click Save.

You are now able to import and push these User's attributes values from/to Box.



Troubleshooting Tips


Appendix A - Managing Groups with Box

The rest of this document provides information about how to manage Groups with Box, and includes the following sections:

There are three ways you can manage your groups when using the Box application. The method you choose primarily depends on whether or not you have preexisting groups in Box, whether you want to manage groups in Okta or Box, and whether certain caveats with each method apply to your deployment. The three group management methods are

The following sections describe when and how each group management method should be used.

Before You Begin

Before you configure group management in Box, you can integrate Active Directory (AD) as a source of both groups and users. AD integration requires that you install the AD Agent. See Installing and Configuring the Okta Active Directory Agent.

Managing Box Groups with Group Push

You can manage your Box groups by adding groups to your Box app in Okta and then configuring group push.

When to Use This Method

Group Push works best when your Box app has no preexisting groups and you want to have AD or Okta manage groups and group memberships in Box. In this scenario, you do not use Box to manage groups or group membership.

If you have an existing Box app that has groups configured, but you want to have AD or Okta manage groups and group membership, you must first migrate your preexisting Box groups into Okta and then push them back into Box as new groups. After you perform this migration, you no longer use the preexisting Box groups. This migration is required because Okta cannot modify and control preexisting groups that were imported from Box.

If you do not want to perform this migration, you can push groups via SAML instead. See Managing Groups in Box Using Push Groups via SAML below for more information.

Adding Your Groups to Box

To add your groups to the Box app, do the following:

  1. From your Administrator Dashboard, select Applications > Box.
  2. See Applications for information on how to add your groups to the app.

Configure Push Groups to Box

Push the groups whose members you added above to Box using the group push feature. See Group Push for more information.

Managing Groups in Box Using Push Groups via SAML

You can manage your Box groups by configuring push groups via SAML.

When to Use This Method

Use this method when you have preexisting groups in Box and you want to be able to do the following:

Configuring Push Groups via SAML

Do the following:

  1. From your Administrator Dashboard, select Applications > Box.
  2. Select the Sign On tab and click the Edit button in the Settings section.
  3. Leave the Default Relay State field blank.
  4. Configure SAML 2.0 for Box.net. Click the View Setup Instructions button and perform the customized procedure that opens.
  5. In the Advanced Sign-on Settings section, configure the following settings:
    • Select the Push Groups via SAML? check box.
    • In the Group Filter field, enter an expression that captures the groups you want to manage. For example, entering AD-.* would capture all groups prefixed with "AD-."
    • Select a Default username format from the drop-down menu.
  6. Click the Save button. 
  7. To configure push groups via SAML to remove group memberships from Box, go to your Box administrator interface, select Enterprise Settings > Security, and make sure you have selected the Remove user from groups upon SSO user login check box. Then click the Save button.

    NoteIf a user is a member of only one group in Okta and AD and is removed from that group, the group membership removal does not occur in Box. When a user is a member of no groups in Okta and AD, the SAML assertion from Okta omits the <groups> element completely (instead of sending an empty <groups> element).  With no <groups> element to inspect, Box does nothing to its groups so the last group membership remains intact in Box until you manually remove it in Box.

With push groups via SAML configured, group memberships in Okta are updated in Box whenever an Okta user signs into Box via SAML. Box assigns new users to the appropriate groups or, when the group does not already exist, it creates a new group and assigns the user to it.

Assigning Group Membership as a User Attribute

You can assign group membership as a user attribute when you have preexisting groups in Box and you want to be able to add users to these groups. This method does not support the ability to create new groups in Box and is not recommended for most scenarios.

Managing Users

To use this group management method, you must have provisioning configured. Do the following:

  1. From the Administrator Dashboard, select Applications > Box
  2. Select the Provisioning tab and then click the Edit button in the Provisioning section.
  3. Select the Enable provisioning features check box.
  4. Click the Authenticate with Box (or Re-authenticate with Box if you have authenticated previously) button and follow the steps in Box to grant access.
  5. Configure your import schedule by selecting the Schedule import drop-down menu and choosing an import interval. We recommend that you import frequently to ensure that your group settings are updated often.
  6. Select Advanced: Configure Import Matching Rules, then and choose the desired setting.
  7. Select Provision new Box accounts from Okta and optionally select Create personal Box folder when new user account is provisioned. If you select the personal folder option, configure the related fields. See Configuring Personal Folder for more information.
  8. In the Update User Attributes section, check the Enable button. 
  9. Click the Save button. 

Adding Okta Users to Your Box Groups

With Box provisioning configured, Okta can import preexisting group information from Box. When you assign the Box app to an Okta user, you must select which preexisting groups you want provisioned to the Okta user in Box.