Configuring the Box Connector

3.1 Basic Configuration Parameters

These are the connection-related parameters that Oracle Identity Governance requires to connect to the Box target application.

Note:

Unless specified, the parameters in the table are applicable to both target and authoritative applications.

Table 3-1 Basic Configuration Parameters for the Box Connector

Parameter	Mandatory?	Description
authenticationType	Yes	Enter the type of authentication used by your target system. The Box target system uses manual input of access token and refresh token for OAuth2.0 authentication. Default value`: Other`
Host	Yes	Enter the host name of the computer hosting your target system. Sample value: `api.box.com/2.0`
clientId	Yes	Enter the client identifier (a unique string) issued by the authorization server to your client application during the registration process. You would have obtained the client ID while configuring the newly registered application. Sample value: `83b-88onw9ddvgy9nnbworruf0x4nre9`
clientSecret	Yes	Enter the secret key used to authenticate the identity of your client application. You obtained the secret key while performing the procedure described in Configuring the Newly Added Application. Sample value: `5Zi1PivsZDd00iHwK1GcZmvv5qNFCvuI`
customAuthHeaders	Yes	Takes access token and refresh token values. Sample value: `"access_token=fjvf0ghwpm3H1gSnWec3NcSVkgUFLIaQ","refresh_token=V1P163HMIC52RDxVE8rwlWHas0w71QWAJ2AXSivEpr6LluxGsQtDB34nxuKHhFJd"`
sslEnabled	Yes	If the target system requires SSL connectivity, then set the value of this parameter to true. Otherwise set the value to false. Default value: `true`
Connector Server Name	No	If you are using Box Connector together with the Java Connector Server, then provide the name of Connector Server.
Port	No	Enter the port number at which the target system is listening. Sample value: `443`
proxyHost	No	Enter the name of the proxy host used to connect to an external target.
proxyPassword	No	Password of the proxy user ID of the target system user account that Oracle Identity Governance uses to connect to the target system.
proxyPort	No	Proxy port number.
proxyUser	No	Proxy user name of the target system user account that Oracle Identity Manager uses to connect to the target system.

3.2 Advanced Settings Parameters

The advanced settings parameters are the configuration-related entries that the connector uses during reconciliation and provisioning operations.

Note:

All parameters in the below table are mandatory

Table 3-2 Advanced Settings Parameters for the Box Connector

Parameter	Description
Bundle Name	This entry holds the name of the connector bundle. Default value: `org.identityconnectors.genericrest`
Bundle Version	This entry holds the version of the connector bundle. Default value: `12.3.0`
Connector Name	This entry holds the name of the connector. Default value: `org.identityconnectors.genericrest.GenericRESTConnector`
httpHeaderAccept	This holds the accept-type expected from the target system in the header. Default value: `application/json`
customPayload	This entry lists the payloads for all operations that are not in the standard format. Default value: `"__ACCOUNT__.__GROUP__.UPDATEOP={ \"user\": { \"id\": \"$(__UID__)$\"}, \"group\": { \"id\": \"$(id)$\" } }","__ACCOUNT__.__GROUP__.CREATEOP={ \"user\": { \"id\": \"$(__UID__)$\"}, \"group\": { \"id\": \"$(id)$\" } }"`
nameAttributes	This entry holds the name attribute for all the objects that are handled by this connector. Default value: `"__ACCOUNT__.login","__GROUP__.name"`
jsonResourcesTagspecialAttributeHandling	This entry holds the json tag value that is used during reconciliation for parsing multiple entries in a single payload. Default value: `"__ACCOUNT__=entries","__GROUP__=entries","__ACCOUNT__.__GROUP__=entries","__ACCOUNT__.email=entries","__ACCOUNT__.__MEMBERSHIP__.__GROUP__=entries","__ACCOUNT__.__MEMBERSHIP__.email=entries"`
specialAttributeHandling	Enter the list of special attributes whose values must be sent to the target system in separate calls, one at a time. If you do not specify a value for this parameter, then the connector will send all values for a given special attribute in a single call. Default value: `"__ACCOUNT__.__GROUP__.CREATEOP=SINGLE","__ACCOUNT__.__GROUP__.UPDATEOP=SINGLE","__ACCOUNT__.email.CREATEOP=SINGLE","__ACCOUNT__.email.UPDATEOP=SINGLE","__ACCOUNT__.role.SEARCHOP=SINGLE","__ACCOUNT__.is_exempt_from_login_verification.SEARCHOP=SINGLE","__ACCOUNT__.is_sync_enabled.SEARCHOP=SINGLE"`
httpHeaderContentType	This holds the content-type expected by the target system in the header. Default value: `application/json`
relURIs (Box)	This entry holds the relative URL of every object class supported by this connector and the connector operations that can be performed on these object classes. Default value: "__ACCOUNT__.CREATEOP=/users","__ACCOUNT__.UPDATEOP=/users/$(__UID__)$","__ACCOUNT__.SEARCHOP=/users?$(Filter Suffix)$&limit=$(PAGE_SIZE)$&offset=$(PAGE_OFFSET)$","__ACCOUNT__.DELETEOP=/users/$(__UID__)$","__GROUP__.SEARCHOP=/groups?$(Filter Suffix)$&limit=$(PAGE_SIZE)$&offset=$(PAGE_OFFSET)$","__ACCOUNT__.__GROUP__.CREATEOP=/group_memberships","__ACCOUNT__.__GROUP__.UPDATEOP=/group_memberships","__ACCOUNT__.__GROUP__.SEARCHOP=/users/$(__UID__)$/memberships?limit=$(PAGE_SIZE)$&offset=$(PAGE_OFFSET)$","__ACCOUNT__.__GROUP__.DELETEOP=/group_memberships/$(__MEMBERSHIP__.id)$","__ACCOUNT__.__MEMBERSHIP__.__GROUP__.SEARCHOP=/users/$(__UID__)$/memberships","__ACCOUNT__.email.UPDATEOP=/users/$(__UID__)$/email_aliases","__ACCOUNT__.email.SEARCHOP=/users/$(__UID__)$/email_aliases?limit=$(PAGE_SIZE)$&offset=$(PAGE_OFFSET)$","__ACCOUNT__.email.DELETEOP=/users/$(__UID__)$/email_aliases/$(__MEMBERSHIP__.id)$","__ACCOUNT__.__MEMBERSHIP__.email.SEARCHOP=/users/$(__UID__)$/email_aliases?limit=$(PAGE_SIZE)$&offset=$(PAGE_OFFSET)$","__ACCOUNT__.role.SEARCHOP=/users/$(__UID__)$?fields=role","__ACCOUNT__.is_sync_enabled.SEARCHOP=/users/$(__UID__)$?fields=is_sync_enabled","__ACCOUNT__.is_exempt_from_login_verification.SEARCHOP=/users/$(__UID__)$?fields=is_exempt_from_login_verification"
statusEnableValue	This entry holds the value of the status attribute in the target system which represents the enable value. Default value: `active`
enableEmptyString	This entry holds the configuration value. If this configuration is set to `true`, the connector will send an empty string instead of null to the target system when any attribute of the Box account of Oracle Identity Governance user is updated with a blank value. Default value: `true`
specialAttributeTargetFormat	This entry lists the format in which a special attribute is present in the target system endpoint. Default value:`"__ACCOUNT__.__GROUP__=group","__ACCOUNT__.__MEMBERSHIP__.__GROUP__=group.id"`
statusAttributes	This entry lists the name of the target system attribute that holds the status of an account. For example, for the __ACCOUNT__ object class that it used for User accounts, the status attribute is accountEnabled. Default value: `__ACCOUNT__.status`
uidAttributes	This entry holds the uid attribute for all the objects that are handled by this connector. Default value: `"__ACCOUNT__.id","__GROUP__.id"`
opTypes	This entry specifies the HTTP operation type for each object class supported by the connector. Default value: `"__ACCOUNT__.CREATEOP=POST","__ACCOUNT__.UPDATEOP=PUT","__ACCOUNT__.DELETEOP=DELETE","__ACCOUNT__.__GROUP__.UPDATEOP=POST","__ACCOUNT__.__GROUP__.DELETEOP=DELETE","__ACCOUNT__.email.UPDATEOP=POST","__ACCOUNT__.email.DELETEOP=DELETE"`
statusDisableValue	This entry holds the value of the status attribute in the target system which represents the disable value. Default value: `inactive`

3.3 Attribute Mappings

The Schema page for a target application displays the default schema (provided by the connector) that maps Oracle Identity Governance attributes to target system columns. The connector uses these mappings during reconciliation and provisioning operations.

Box User Account Attributes

Table 3-3 lists the user-specific attribute mappings between the process form fields in Oracle Identity Governance and Box application columns. The table also lists whether a specific attribute is used during provisioning or reconciliation and whether it is a matching key field for fetching records during reconciliation.

If required, you can edit the default attribute mappings by adding new attributes or deleting existing attributes as described in Creating a Target Application in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

Table 3-3 Default Attribute Mappings for Box User Account

Identity Attribute	Target Attribute	Data Type	Mandatory Provisioning Property?	Provision Field?	Recon Field?	Key Field?	Case Insensitive?
Login	__NAME__	String	Yes	Yes	Yes	No	No
Name	name	String	Yes	Yes	Yes	Yes	No
Role	role	String	No	Yes	Yes	No	No
Language	language	String	No	Yes	Yes	No	No
Enable Sync	is_sync_enabled	String	No	Yes	Yes	No	No
Job Title	job_title	String	No	Yes	Yes	No	No
Phone	_ENABLE_	String	No	Yes	Yes	No	No
Address	address	String	No	Yes	Yes	No	No
Space Amount	space_amount	String	No	Yes	Yes	No	No
Timezone	timezone	String	No	Yes	Yes	No	No
Exempt From Login	is_exempt_from_login	String	No	Yes	Yes	No	No
Id	_UID_	String	No	Yes	Yes	No	No
Status	_ENABLE_	String	No	No	Yes	No	No

Figure 3-1 shows the default User account attribute mappings.

Figure 3-1 Default Attribute Mappings for Box User Account

Description of "Figure 3-1 Default Attribute Mappings for Box User Account "

Groups Entitlement

Table 3-4 lists the group forms attribute mappings between the process form fields in Oracle Identity Governance and Box target application attributes. The table lists whether a given attribute is mandatory during provisioning. It also lists whether a given attribute is used during reconciliation and whether it is a matching key field for fetching records during reconciliation.

If required, you can edit the default attribute mappings by adding new attributes or deleting existing attributes as described in Creating a Target Application in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

Table 3-4 Default Attribute Mappings for Groups Entitlement

Display Name	Target Attribute	Data Type	Mandatory Provisioning Property?	Recon Field?	Key Field?	Case Insensitive?
Group Name	__GROUP__~__GROUP__~id	String	No	Yes	Yes	No

Figure 3-1 shows the default attribute groups mapping.

Figure 3-2 Default Attribute Mappings for Groups Entitlement

Description of "Figure 3-2 Default Attribute Mappings for Groups Entitlement"

3.4 Correlation Rules

Learn about the predefined rules, responses and situations for a Target application. The connector use these rules and responses for performing reconciliation.

Predefined Identity Correlation Rules

By default, the Box connector provides a simple correlation rule when you create a target application. The connector uses this correlation rule to compare the entries in Oracle Identity Governance repository and the target system repository, determine the difference between the two repositories, and apply the latest changes to Oracle Identity Governance.

Table 3-5 lists the default simple correlation rule for Box connector. If required, you can edit the default correlation rule or add new rules. You can create complex correlation rules also. For more information about adding or editing simple or complex correlation rules, see Creating a Target Application in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

Table 3-5 Predefined Identity Correlation Rule for a Box Target Application

Target Attribute	Element Operator	Identity Attribute	Case Sensitive?
__NAME__	Equals	User Login	No

In this identity rule:

__NAME__ is a single-valued attribute on the target system that identifies the user account.
User Login is the field on the OIG User form.

Figure 3-3 shows the complex correlation rule for Box target application.

Figure 3-3 Complex Correlation Rule for a Box Target Application

Description of "Figure 3-3 Complex Correlation Rule for a Box Target Application"

Predefined Situations and Responses

The Box connector provides a default set of situations and responses when you create a target application. These situations and responses specify the action that Oracle Identity Governance must take based on the result of a reconciliation event.

Table 3-5 lists the default situations and responses for Box target application. If required, you can edit these default situations and responses or add new ones. For more information about adding or editing situations and responses, see Creating a Target Application in Oracle Fusion Middleware Performing Self Service Tasks with Oracle Identity Governance.

Table 3-6 Predefined Situations and Responses for a Box Target Application

Situation	Response
No Matches Found	None
One Entity Match Found	Establish Link
One Process Match Found	Establish Link

Figure 3-4 shows the situations and responses for Box that the connector provides by default.

Figure 3-4 Predefined Situations and Responses for a Box Target Application

Description of "Figure 3-4 Predefined Situations and Responses for a Box Target Application"

3.5 Reconciliation Jobs

Learn about reconciliation jobs that are automatically created in Oracle Identity Governance after you create a target application for your target system.

User Reconciliation Job

You must specify values for the attributes of user reconciliation jobs.

The Box Target User Reconciliation job is used to fetch all user records from the target system.

Table 3-7 Parameters of the Box Target User Reconciliation Job

Attribute Description

Application Name

Name of the application you created for your target system. This value is the same as the value that you provided for the Application Name field while creating your target application.

Do not modify this value.

Filter Suffix

Enter the search filter for fetching records from the target system during a reconciliation run.

Sample value: /0e220301db039a00b88df7a0cf9619

See Configuring Reconciliation Jobs for more information about filtered reconciliation.

Object Type

Type of object you want to reconcile.

Default value: User

Reconciliation Jobs for Lookup Field Synchronization

The lookup definitions are used as an input source for lookup fields in Oracle Identity Governance.

The Box Group Lookup Reconciliation Scheduled job is used for lookup fields synchronization.

Table 3-8 Parameters of the Box Group Lookup Reconciliation Scheduled Job

Attribute	Description
Application Name	Name of the application you created for your target system. This value is the same as the value that you provided for the Application Name field while creating your target application. Do not modify this value.
Lookup Name	Enter the name of the lookup definition in Oracle Identity Governance that must be populated with values fetched from the target system. Default value: `Lookup.box.groups`
Object Type	Type of object you want to reconcile. Default value: `_Group_`
Code Key Attribute	Name of the connector attribute that is used to populate the Code Key column of the lookup definition (specified as the value of the Lookup Name attribute). Default value: `__UID__`
Decode Attribute	Name of the connector attribute that is used to populate the Decode column of the lookup definition (specified as the value of the Lookup Name attribute). Default value :`__NAME__`

Box Update Access Token Job

Access token configured as part of IT resource will expire in 60 minutes and refresh token will expire in 60 days. Box Update Access Token Job is used to keep the value of the access token (in the IT resource) always valid. Every 50 minutes, this job is scheduled to run periodically.

Note:

If for some reason this scheduler is not run for more than 60 days, then the refresh token value in IT resource would have expired due to which if you run the Box Update Access Token Job after 60 days, it will fail. In such cases, a new access token and refresh token has to be generated manually.

Table 3-9 Attributes of the Box Update Access Token Job

Attribute	Description
Access Token Endpoint	This attribute holds the Box REST endpoint to get the new access token. Default value: `https://app.box.com/api/oauth2/token`
IT Resource Name	Enter the name of the IT resource for the target system installation from which you want to reconcile user records. Default value: `Box`
Task Name	This attribute holds the name of the scheduled task. Default value: `Box Update Access Token` You must not change the default value.
Start Date	This attribute holds the Start Date and time of job. Select current time and date from the Calender drop-down.