Fischer's Box Connector supports exporting and importing user accounts on a box system.
Functionalities
Provisioning Integration
Data Format |
Export |
Create |
Modify |
Delete |
Trigger |
---|---|---|---|---|---|
User | Yes |
Yes | Yes | Yes | No |
Prerequisites
Ensure that these prerequisites are satisfied:
- Create an Administrator account on the Box system.
- Generate access tokens for the administrative account from the Box system to establish connection and to manage accounts on the Box connected system.
Generating Access Tokens to make Box API Call
Following are the steps to generate access tokens to make Box API calls using OAuth2 authentication.
- To configure OAuth2 Parameters, go to developers console page using the link https://app.box.com/developers/console. Provide Box admin credentials to get the developer console page. Click `Create New App' in `My Apps' to create new box application.
- Select the type of Application. Click Next.
- Select the ‘Authentication Method’ as “Standard OAuth 2.0 (User Authentication)” and Click Next.
- Enter your application name. Click on ‘Create App’ to create your application.
- In the created Application, ‘Client ID’ and ‘Client Secret’ are available in ‘OAuth 2.0 Credentials’ configuration.
- Select ‘Application Scopes’ to read/write files and folders, manage users, manage groups etc.
- Enter the OAuth 2.0 Redirect URI which is used to create connected system parameter 'Access Tokens (JSON)*'. We can use any of the following three options.
- The Box server prefer secure 'SSL enabled' redirect URI (starts with https). The Identity Server should be configured as SSL enabled. Click 'Save Changes' button in box application configuration page.
- Box supports non-secure mode when the token is generated from server machine itself. Click 'Save Changes' button in box application configuration page. For Example: http://localhost:8080/identity/boxauth These first two options redirect the call to Fischer Identity Server and can easily generate box 'Access Tokens' from the connected system details page itself. Click 'Get Token' button in box connected system details page. A new 'Box Log in' window will open and provide box credentials. Click 'Grant access to Box' to get the access token. Copy and paste the access tokens in connected system details page. The screens are shown below.
- In this third option, we have to manually generate box 'access code' and 'access token' with the help of external calls described below. The 'Redirect URI' can be set as 'http://0.0.0.0'
- Select any Rest Client application to call Box. Chrome Rest Client Postman is one of the recommended applications. To install Postman,
- Change call method combo from GET to POST and set the URL https://api.box.com/oauth2/token.
- Select the first result to show the below page:.
- Use ADD TO CHROME button on the top right to install it as a chrome app.
- Change call method combo from GET to POST and set the URL https://api.box.com/oauth2/token.
- Select any Rest Client application to call Box. Chrome Rest Client Postman is one of the recommended applications. To install Postman,
-
- To initialize Postman to call Box,
- Select Postman from Chrome apps.
- Signup providing Email, Name and Password.
- Now Postman is ready to make calls as shown below.
-
Change the below settings:
Change call method combo from GET to POST and set the URL https://api.box.com/oauth2/token. Select Body tab, select x-www-form-urlencoded option and provide the below parameters:Name Value grant_type authorization_code client_id Your <client_id> from first step client_secret Your <client_secret> from first step code Access code to be generated as described in next step.
Save the settings to re-use in future calls.
- To generate Access Code:
- To initialize Postman to call Box,
- The Box server prefer secure 'SSL enabled' redirect URI (starts with https). The Identity Server should be configured as SSL enabled. Click 'Save Changes' button in box application configuration page.
- Update the below URL corresponding to your Box app.
https://account.box.com/api/oauth2/authorize?response_type=code&client_id=<ClientID>& state=<SomeToken>
An example is
https://account.box.com/api/oauth2/authorize?response_type=code&client_id=t0p9kn793 qwuq9genz7t6wp90247jeao&state=security_tokenABC - Select a browser and provide the URL above.
- Box Login page will be displayed.
- Provide OTP, if prompted and proceed.
- Once the OTP is submitted, the below page displays:
- Click Use Grant access to Box button to proceed.
The access code will be send to the redirect URL. Since redirect URL was configured as http://0.0.0.0 the code will be visible in the browser URL.
Copy the access code from the URL. For example, in the above image, the access code is “GomTl9ewgOfKmqzwMk3nuQsFkSosO73y”.
-
- To generate Access Tokens,
-
Note: These steps must be completed in 30 seconds after step 5 since the code is valid only for 30 seconds.
-
- Select Postman from Chrome apps.
- Load the saved Box call settings.
- Paste the access code received in the previous step as code.
- Click the Send button to receive the access tokens as JSON shown below. Use them as the access tokens when connected system is created. Remove the new line chars from JSON since text fields are used to enter the token in connected system details page
Creating the Connected System in the Admin UI
Log in to Identity Administration and click the Systems tab.
-
On the Connected System View page, click the Add button and select the Box connected system from the Type drop-down list. The default values display:
-
Enter the desired information:
Definition Supported Connectors
Displays whether the connected system is Identity only, Provisioning only, or both.
Type
Select the connected system type. Name The name for this connected system. Note: The name cannot be modified later. Display Name The display name of the new connected system. Description The description of the connected system. Associated With
Select how the connector associated with this system will run:
- Server (default) - Runs locally on the Provisioning/Identity Server.
- Global Identity Gateway - Runs remotely on a Global Identity Gateway cluster member. Note: Only GIG clusters that have at least one registered and enabled member will display in this list.
- See Using the Global Identity Gateway with Connected Systems for additional information.
Password Reset By Enables administrators to configure password management functions normally available to Users and OBO (On Behalf Of) Users: - OBO User Only - Connected system and account association information is displayed only in Self-Service user management (for OBO Users). OBO Users can reset passwords for accounts on this connected system. Administrators can perform all user management functions for this connected system (e.g., enable/disable, validate, associate user, and password reset). End users will not see their accounts on this connected system in Self-Service and Kiosk; therefore, they cannot reset passwords for accounts on this connected system.
- Users and OBO User - Connected system and account association information is displayed in Self-Service password reset, Self-Service - Kiosk, and Self-Service user management. Self-Service users, Kiosk users, and OBO Users can reset passwords for accounts on this connected system. Administrators can perform all user management functions for this connected system (e.g., enable/disable, validate, associate user, and password reset).
- External - Connected system and account association information is not displayed in Self-Service password reset, Self-Service - Kiosk, and Self-Service user management. Self-Service users, Kiosk users, and OBO Users cannot reset passwords for accounts on this connected system.
Note: When user management configuration enables OBO Users to perform password resets, this definition must be set to OBO User Only or Users and OBO User. For connectors that support Provisioning only, there is no password reset capability.
Provisioning Option Select the provisioning option: - Automated (default) - The connected system functions as a normal connected system; there are no restrictions.
- Administrative - The connected system cannot be used as an object in a workflow.
Enable HPAM Support Select to make the connected system HPAM enabled (default: cleared). Note: This can only be set for systems that support Identity. Enable Transfer of Accounts
Select to make the transfer of Accounts enabled (default cleared). Connection Information Client Id
Enter the client_id given in the OAuth2 Parameters section of the Box Application. (Obtained from Step 5 of Generating Access Tokens to make Box API Call) Client Secret
Enter the client_secret given in the OAuth2 Parameters section of the Box Application. (Obtained from Step 5 of Generating Access Tokens to make Box API Call) Access Tokens (JSON)
Enter the JSON from the Postman App. The newline chars from JSON should be removed. (Obtained from Step 7 of Generating Access Tokens to make Box API Call) -
Click the Test Connection button to test the Connection Information:
- If successful, one or both of these messages may display:
Message: Connection from Studio to the connected system was established successfully.
- If unsuccessful, one or both of these messages may display:
Error: Failed to establish connection from Studio to the connected system.
Note: If the connection fails, additional messages may display providing more information regarding the failure. -
Click the Apply button to apply changes. The Category Association window displays.
Select one or more object categories from the Available Categories list or enter a category name and click the Search button to find a specific category to select. If there are no available categories to select, proceed to Step 6.
- Click the Add button to associate the selected object categories to the connected system.
Click OK to accept selected categories.
See Copying, Modifying, and Deleting Connected Systems for additional information.
Using the Connected System for Provisioning
Perform these procedures to configure the connector:
- Configuring for Export
- Configuring for Import
- Connector Details for Provisioning
- Lookup Data
Note: If the number of records to be processed exceeds one thousand, we recommend configuring the workflow to use bulk mode, which lowers the memory consumption of the system by streaming data to files. Because data is streamed for every task, performance of the workflow execution will be decreased due to increased read-write operations. See the Workflow and Connectivity Studio document for details on how to configure bulk mode.
Configuring for Export
Perform these procedures to configure the connector for data export:
- Configuring the Export Connector
- Configuring the Export Link
From the Workflow and Connectivity Studio, select the Box-UserExport workflow listed under the projects folder.
If a workflow does not already exist, create an export workflow. See Workflow and Connectivity Studio for details on creating export workflows.
Configuring the Export Connector
- In the Design pane, double-click the export object (the first workflow object after the Start object). The Configure Data Source window displays:
-
From the Configure Plug-in tab, set these properties as required:
Associated Connected System Select the connected system from the list. The export operation will be done from this connected system. Data Formats Select the type of data format to use: User. DeltaExportMode Select the type of attribute to export if a change takes place (this works in conjunction with ExportMode when DeltaExport is selected):
- OnlyChangedAttributes - Performs a partial export of only the changed attributes from the last time the query was run.
- ChangedAndMandatoryAttributes (default) - Performs a partial export of both changed and mandatory attributes from the last time the query was run. Mandatory attributes are exported whether they have been changed or not.
- AllAttributes - Performs a full export of all attributes that contain a value.
DynamicConnectedSystem Select the global variable to use as the dynamic connected system name. This works in conjunction with DynamicConnectedSystemOption when GlobalVariable is selected. DynamicConnectedSystemOption Select how to control Dynamic System Support (DSS): - None - There will not be any Dynamic System Support.
- Transaction-SystemName - The value of the Transaction-SystemName attribute in data will be used as the dynamic connected system. The connected system name must be passed as the value of the attribute Transaction-SystemName; if it is missing in data, the operation will fail.
- GlobalVariable - Select a global variable to use as the dynamic connected system name from the property DynamicConnectedSystem.
ExecuteGIGAssociatedTaskAsynchronously If this property is True, GIG associated tasks will execute asynchronously.
ExportMode
Select the type of data to export:
- FullExport - Exports all attributes.
- DeltaExport - Exports changed, mandatory, or all attributes, depending on the DeltaExportMode property setting.
Filter Specify search criteria to determine the objects to be exported from the container specified in ExportDN. Use the Set Filter button that becomes active to create a filter. See "Set Filter" on page 34 for additional information. FoldSubRecords
If set to TRUE, sub records are folded and returned as attributes. GetUserByEmail
Configuration property with the email of the user. If this property is configured, other export related configuration properties (Filter, Maxresults) are ignored. MaxResults
Select the maximum number of results that can be returned. -
(Optional) Select the Attributes tab. Only standard attributes display:
Modify schema attributes using these buttons.Add Adds additional attributes to the list. The Add New Attribute dialog displays. Export Exports the schema list to an XML file. Import Imports the schema list from an XML file. Refresh Schema Dynamically discovers the schema from the target LDAP system. It also includes local as well as global attributes added in the Studio. Reset Schema
Resets the schema definition to the default schema prepackaged with the IdM Suite, plus any global variable added. - (Optional) Select the Appearance tab to change how the Connected System object displays in the Design pane.
-
Click OK to save any changes and return to the Workflow and Connectivity Studio window.
Configuring the Export Link
-
In the Design pane, double-click the export link between the export object (the first workflow object after the Start object) and the Data Mapper object. The Configure Link window displays:
Source Attributes Select the attributes to export. Selected Attributes Displays default attributes and those attributes that have been selected from the Source Attributes.
Notes: The check boxes are used only for delta export operations. These checked attributes will always be exported whether they were changed or not. Usually, the attributes that are selected as mandatory attributes help in identifying or verifying an entry when completing mapping functions.Advanced Settings Displays the Configure Attributes window for configuring advanced settings for attributes. See the Configure Attributes window on page 39 for additional information. - From the Attribute Selection tab, select attributes to export.
Usually, these attributes that are selected (mandatory attributes) help in identifying or verifying an entry when completing Data Mapper functions.
- Click OK to save any changes and return to the Workflow and Connectivity Studio window.
- Deploy the workflow by selecting Deploy ► New Deployment. See the Workflow and Connectivity Studio documentation for details of deployment options.
- Manage and run the deployed workflow from the Admin UI ► Server tab. See the Identity Suite Administration documentation for details.
Configuring for Import
Perform these procedures to configure the connector for data import:
- Configuring the Import Connector
- Configuring the Import Link
From the Workflow and Connectivity Studio, select the Box UserAdd, UserModify, or UserDelete workflow listed under the projects folder.
If a workflow does not already exist, create an import workflow. See the Workflow and Connectivity Studio documentation for details on creating import workflows.
Configuring the Import Connector
- In the Design pane, double-click the import object (the last workflow object). The Configure Data Source window displays:
-
From the Configure Plug-in tab, set these properties as required:
Associated Connected System Select the connected system from the list. The import operation will be done to this connected system. Data Formats Select the type of data format to use: User. DynamicConnectedSystem Select the global variable to use as the dynamic connected system name. This works in conjunction with DynamicConnectedSystemOption when GlobalVariable is selected. DynamicConnectedSystemOption Select how to control Dynamic System Support (DSS): - None - There will not be any Dynamic System Support.
- Transaction-SystemName - The value of the Transaction-SystemName attribute in data will be used as the dynamic connected system. The connected system name must be passed as the value of the attribute Transaction-SystemName; if it is missing in data, the operation will fail.
- GlobalVariable - Select a global variable to use as the dynamic connected system name from the property DynamicConnectedSystem.
See the Dynamic System Support appendix in the Workflow and Connectivity Studio document for additional information.
ExecuteGIGAssociatedTaskAsynchronously If this property is True, GIG associated tasks will execute asynchronously. Id * Enter the attribute that contains the value used to uniquely identify the user account user ID on the connected system. loginId * Enter the attribute that contains the value used to uniquely identify the user account login ID on the connected system. SubRecordsInFoldedState
When set to TRUE, the connector accepts multi-level attributes in a folded state.
* accountDN, Id, and loginId are used by the Provisioning Policy and IdentityHub features to populate the ACCOUNT_DN, ACCOUNT_ID, and ACCOUNT_USERNAME columns of the FISC_USER_ACCOUNT table of the Product database. See the ‘Provisioning Policy’ and ‘Provisioning Using the IdentityHub’ chapters of the Identity Suite Administration Guide for details.
Hover the pointer over a property to view its description. (Optional) Select the Attributes tab. Only standard attributes display:
Modify schema attributes with the buttons.- (Optional) Select the Appearance tab to change how the Connected System object displays in the Design pane.
-
Click OK to save any changes and return to the Workflow and Connectivity Studio window.
Configuring the Import Link
-
In the Design pane, double-click the import link between the Data Mapper object and the import object (the last workflow object). The Configure Link window displays:
Source Attributes Select the attributes to import. Check for attribute-level auditing
If auditing is enabled and these attributes below are checked, Provisioning will log all events for auditing purposes. Selected Attributes Displays default attributes and those attributes that have been selected from the Source Attributes. Note: The default attributes are those that are commonly used to create a new user. Advanced Settings Displays the Configure Attributes window for configuring advanced settings for attributes. Under the Encrypted column, check the box of any attribute that needs to be encrypted.
Under the Diff With Target column, check the box of any attribute to update using differencing (DiffWithTarget, AddDiffWithTarget, and RemoveDiffWithTarget).Audit Key
Select the attribute to associate with the Audit Key. From the Attribute Selection tab, select attributes to import.
(Optional) Select the Appearance tab to change how the link displays in the Design pane.
- Click OK to save any changes and return to the Workflow and Connectivity Studio window.
Deploy the workflow by selecting Deploy ► New Deployment.
See the Workflow and Connectivity Studio document for details of deployment options.Manage and run the deployed workflow from the Admin UI ► Server tab.
See the Identity Suite Administration Guide for details.
Connector Details for Provisioning
Configuration import properties accountDN, Id, and loginId are used by the Provisioning Policy and IdentityHub features to populate the ACCOUNT_DN, ACCOUNT_ID, and ACCOUNT_USERNAME columns of the FISC_USER_ACCOUNT table of the Product database. See the ‘Provisioning Policy’ and ‘Provisioning Using the IdentityHub’ chapters of the Identity Suite Administration Guide for details.
This table shows the default attributes specified for these properties for the connected system:
Identity Property |
System Attribute |
---|---|
id | |
login id |
Box Connector Attributes
The items in the Export, Create, Modify, and Delete columns have these meanings:
- Y = Yes (attribute is supported for this operation)
- N = No (attribute is not supported for this operation)
- R = Required (attribute is mandatory for this operation)
User Data Format
The following table outlines the supported user attributes.
Name |
MV | Export |
Create |
Modify |
Delete |
Import |
Description |
---|---|---|---|---|---|---|---|
Address | N | Y | Y | Y | Y | Y | |
Alias | Y | Y | Y | Y | Y | Y | |
AvatarURL |
N | Y | N | N | N | N | |
CanSeeManagedUsers | N | Y | Y | Y | Y | Y | |
CreatedAt | N | Y | N | N | N | N | |
N | Y | R | R | R | Y | Note: Email (set during user creation) should |
|
EmailAlias->Email | Y | Y | N | N | N | N | |
EmailAlias->IsConfirmed | Y | Y | N | N | N | N | |
HostName | N | Y | N | N | N | N | |
Id | N | Y | N | N | N | N | |
IsExemptFromDeviceLimits | N | Y | Y | Y | Y | Y | |
IsExemptFromLoginVerification | N | Y | Y | Y | Y | Y | |
IsExternalCollabRestricted | N | Y | N | N | N | N | |
IsPasswordResetRequired | N | Y | Y | Y | Y | Y | |
IsPlatformAccessOnly | N | Y | N | N | N | N | |
IsSyncEnabled | N | Y | Y | Y | Y | Y | |
JobTitle | N | Y | Y | Y | Y | Y | |
Language | N | Y | Y | Y | Y | Y | |
MaxUploadSize | N | Y | N | N | N | N | |
MemberOf->GroupName | Y | Y | Y | Y | Y | Y | |
MemberOf->Role | Y | Y | Y | Y | Y | Y | |
MoveFolderToUserEmail | N | N | N | Y | Y | Y | The email ID of the user to whom the files and folders are to be moved during a user modify/delete. |
MyTags | Y | Y | N | N | N | N | |
Name | N | Y | R | Y | Y | Y | |
Original_Email | N | N | Y | Y | Y | Y | Mandatory for Rename operation. |
Phone | N | Y | Y | Y | Y | Y | |
RemoveEnterprise | N | N | N | Y | N | Y | Set this attribute to True during modify if the user is to be set as a Free user and not as an Enterprise user. |
Role | N | Y | Y | Y | Y | Y | |
SpaceAmount | N | Y | Y | Y | Y | Y | |
SpaceUsed | N | Y | N | N | N | N | |
Status | N | Y | Y | Y | Y | Y | |
Timezone | N | Y | Y | Y | Y | Y |
Lookup Data
To filter data, use the Data Mapper rule Lookup Data
- Log in to the Workflow and Connectivity Studio and double-click the Data Mapper object on the Design pane.
The Configure Data Mapper window displays.
Select the Lookup Data rule under the Mapping Rule column and then click the Source Value.
The Configure Lookup window displays.Select the Box connected system from the Select System drop down list.
In the Enter Lookup Prefix field, enter the prefix to be added to the Lookup fields.
- Select the Lookup Type (User By Email and User By Filter) from the drop-down list.
- Select the Pick button along the Email / Filter to pick the email or filter for lookup.
- Select the Fields Pick button to pick the attributes for lookup.
- Select the Exit as Mapper Task Failed on Lookup Failure check box to exit the task with Failed status on lookup failure. It will not process the succeeding entries and will ignore the already processed entries and will not return any data. This is selected by default.
- Click OK.