Box Integration

 

Vendor: Box

Integration Type:

 

Authentication

In order to use further integrations with your SaaS vendors, it's necessary to configure the  security authentication and authorization method required by each vendor. Each vendor have their own authentication type requirement. Oomnitza currently provides authorization for "API Key", "Basic Auth", "OAuth2.0" and "AWS Auth". 

Additional information about the Credential Vault can be found here: Credentials Table.

 

OAuth2.0

Please follow the following steps to get new access token which can be used in Oomnitza API pre-sets and SaaS User Role block.

  1. Please follow the documentation to create an OAuth2.0 app and keep your Client ID, Client Secret and Scope to be used later in configuring your credential setup within Oomnitza (Step 8)
  2. Go to Oomnitza "Settings" page and select "Credentials"
  3. Click the '+' icon in the top right corner to add a new credential. A pop-up will appear: mceclip0.png
  4. Type the "Name" which helps you identify the credential, example "Box OAuth2.0"
  5. Enter the "Owner" of the credential (optional), possibly the creator of this credential.
  6. Click the "Authorization" tab and select "OAuth 2.0" from the "Authorization type" dropdown.mceclip0.png
  7. Select your "Saas" vendor, "Box", from the SaaS dropdown
  8. Type the Client ID, Client Secret and Scope you created in your OAuth2.0 App (Step 1 above)
  9. Click "Authenticate" button which will prompt you to log into "Box" and authorize the request
  10. Type a useful "Description" which will help you identify the credential (optional)
  11. Click the "Create" button
  12. Finally, you should see the credential you created in the credentials list

Documentation Links:

 

SaaS User Role Block 

Please work through the following steps to configure the SaaS User Role Block for Box. As Box does not currently provide the User Role or the Last Login date/time, we will use this configuration to provide you with confirmation of the actual users that are logging in and using Box in your environment. All users that are confirmed as being part of your Box integration will display 'User' in the Role section of the SaaS Users UI.

 

Pre-requirements:

1. Box Business Account is required for integrations to function correctly. (Box Individual is not covered)

2. A Box Credential is added using OAuth2.0 Authentication method as described above.

3. Your Box SaaS and Contract details with Users are already available within Oomnitza 

 

Steps:

1. Navigate to "Software>Workflow>SaaS Users" as per screenshot below.

mceclip0.png

2. From the SaaS Users Workflow page, select the "Add" button in the top right of your screen, above the grid.

mceclip1.png

3. Give your new Workflow a "Workflow name" (mandatory) and a "Workflow description" (optional) before selecting "Add Item" to create it.

4. From the "Tools" section on the left, drag the "SaaS User Role retrieval block" onto the "Sandbox" section.

Note: All workflows must start with the "Begin" block. The configuration for SaaS User Role blocks can be found here: https://oomnitza.zendesk.com/hc/en-us/articles/360053185893

5. To configure the "SaaS User Role retrieval block", you simply select "Edit" on this block.

6. You will be presented with a two step wizard. Search for the SaaS of choice, in this case, 'Box'. Select your SaaS using the '>' arrow control as high-lighted below to proceed with the configuration.

7. The "Name", "Description" and "Doculink" are all provided for you. You need to select the 'Credential' you created previously for Box, using the OAuth2.0 authentication method. 

Note: With "Deactivated User" selected, we will automatically reconcile deactivated users from your SaaS system (Box) back into Oomnitza.

 

8. Finally, select "Save" and your "SaaS User Role retrieval block' configuration is complete.

9. Your new workflow is ready to run, based off the "Actions" selected if the "Begin" block or else you can run it manually from here.

 

Box "User Role" 

Now that your SaaS User Role block has been setup and the workflow has run, you will be able to get confirmation of actual Users within your organization that use Box. The Role field will be populated by 'User' in this case.

 

Steps:

1. Navigate to "Software>SaaS" and select your software entry for Box. Note, that we are continuing to use Zoom for illustrative purposes.

2. From the dialog, navigate to "Users"

mceclip2.png

3. From within "Users", the "Role" will be populated with the word 'User' to confirm that this user has been found in your Box SaaS.

mceclip3.png

 

Documentation Links:

 

API block (Presets)

The following Box API block Presets are available:

 

Prerequisites:

1. Box Business Account is required for integrations to function correctly. (Box Individual is not covered)

2. A Box Credential is added using OAuth2.0 Authentication method as described above.

3. Your Box SaaS and Contract details with Users are already setup within Oomnitza 

4. You have run a workflow similar to above which would populate Oomnitza with the actual Box User Role and Last Login date from your Box SaaS. 

 

Box Deactivate User

Using this setup outlined below, you can create a workflow that would automatically deactivate a Box user account within your Box SaaS which was deactivated from within Oomnitza. 

 

Steps:

1. Navigate to "Software>Workflow>SaaS Users" as per screenshot below.

mceclip0.png

2. With "Workflow: SaaS Users" now selected, you can select the "Add" button in the top right of your screen, above the grid.

mceclip1.png

3. Give your new Workflow a "Workflow name" (mandatory) and a "Workflow description" (optional) before selecting "Add Item" to create it.

4. From the "Tools" section, drag the "API block" onto the "Sandbox" section.

5. To configure the "API block", you simply select "Edit".

6. Select "Show Presets" from the API block dialog. 

7. Search for you Vendor, in this case "Box"

8. "Apply" the Preset you wish to use, "Box Deactivate User" .

9. A confirmation message will appear on screen your and the URL will be populated on the dialog.

10. You can update the current "Name" on the dialog before moving onto the "Authorization" tab

11. Set the "Type" to "OAuth2.0" and select the "Credentials" that you have previously created as part of the OAuth2.0 authentication method.

12. Finally, select "Save" and your "API block' configuration is complete.

13. Your new workflow is ready to run, based off the configuration of the "Begin" block.

 

Box Delete User

Using this setup outlined below, you can create a workflow that would automatically delete a Box user account within your Box SaaS which was deactivated from within Oomnitza. 

 

Steps:

1. Navigate to "Software>Workflow>SaaS Users" as per screenshot below.

mceclip0.png

2. With "Workflow: SaaS Users" now selected, you can select the "Add" button in the top right of your screen, above the grid.

mceclip1.png

3. Give your new Workflow a "Workflow name" (mandatory) and a "Workflow description" (optional) before selecting "Add Item" to create it.

4. From the "Tools" section, drag the "API block" onto the "Sandbox" section.

5. To configure the "API block", you simply select "Edit".

6. Select "Show Presets" from the API block dialog. 

7. Search for you Vendor, in this case "Box"

8. "Apply" the Preset you wish to use, "Box Delete User" .

9. A confirmation message will appear on screen your and the URL will be populated on the dialog.

10. You can update the current "Name" on the dialog before moving onto the "Authorization" tab

11. Set the "Type" to "OAuth2.0" and select the "Credentials" that you have previously created as part of the OAuth2.0 authentication method.

12. Finally, select "Save" and your "API block' configuration is complete.

13. Your new workflow is ready to run, based off the configuration of the "Begin" block or else you can run it manually from here.

 

Notes:

  • The Box Delete preset will fail if the user still owns any content. We suggest you move the content prior to deleting or use the 'force' field to delete the user and their files. You can add 'force = true' within the API query parameters.

Box Transfer Owned Folder

Using this setup outlined below, you can create a workflow that would automatically transfer content owner by a Box user to somebody else. You can use this as a preset in a workflow before you may want to delete a user in order to safeguard content. 

 

Steps:

1. Navigate to "Software>Workflow>SaaS Users" as per screenshot below.

mceclip0.png

2. With "Workflow: SaaS Users" now selected, you can select the "Add" button in the top right of your screen, above the grid.

mceclip1.png

3. Give your new Workflow a "Workflow name" (mandatory) and a "Workflow description" (optional) before selecting "Add Item" to create it.

4. From the "Tools" section, drag the "API block" onto the "Sandbox" section.

5. To configure the "API block", you simply select "Edit".

6. Select "Show Presets" from the API block dialog. 

7. Search for you Vendor, in this case "Box"

8. "Apply" the Preset you wish to use, "Box Transfer Owned Folder" .

9. A confirmation message will appear on screen your and the URL will be populated on the dialog.

10. You can update the current "Name" on the dialog before moving onto the "Authorization" tab

11. Set the "Type" to "OAuth2.0" and select the "Credentials" that you have previously created as part of the OAuth2.0 authentication method.

12. Finally, select "Save" and your "API block' configuration is complete.

13. Your new workflow is ready to run, based off the configuration of the "Begin" block or else you can run it manually from here.

 

Notes:

  • You need to specify the user id of the user who you want to transfer the content to. To do this you must log into the admin console of your Box account. Navigate to Content in the left column, select the user you wish to move the content to. In the url in your browser you will find the user id for the selected user, example, https://app.box.com/master/content/12345678910/0/0
    • The User ID here for where the content will be moved to is "123456798910"
  • Update the Body section of the API Preset:
    • From: {"owned_by": {"id": "[[OwnerId:Shorttext]]"}}
    • To: {"owned_by": {"id": "12345678910"}}
  • As mentioned above, you may wish to put this as a prior step in the delete workflow, if you don't want to 'force' a deletion through:

transfer.png

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk