Box connector

This is a SaaS common connector.

The Box connector lets you manage Box service accounts and synchronize accounts and groups between Box and the IDM managed user repository.

This topic describes how to install and configure the Box connector and how to perform basic tests to ensure that it’s running correctly.

Before you start

The instructions in this guide assume you have a Box Administrator Account and you have created and authorized a Custom Application, as described in the Box Documentation. Before you configure the connector, log in to your administrator account and note the following information:

Client ID
Client Secret
Authentication Method
Grant Type
Subject Type
Subject ID
Service Uri
Token Endpoint

Install the Box connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector	IDM	RCS
Box	No	No

Download the connector .jar file from Backstage.

If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:
```
mv ~/Downloads/box-connector-1.5.20.26.jar /path/to/openidm/connectors/
```
If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the Box connector

Create a connector configuration using the IDM admin UI:

From the navigation bar, click Configure > Connectors.
On the Connectors page, click New Connector.
On the New Connector page, type a Connector Name.
From the Connector Type drop-down list, select Box Connector - 1.5.20.26.
Complete the Base Connector Details.

For a list of all configuration properties, refer to Box Connector Configuration
Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

The following excerpt shows sample configuration properties:

"configurationProperties": {
  "serviceUri" : "_CHANGEME_",
  "tokenEndpoint" : "_CHANGEME_",
  "clientId" : "_CHANGEME_",
  "clientSecret" : "_CHANGEME_",
  "acceptSelfSignedCertificates" : true,
  "disableHostNameVerifier" : true,
  "authenticationMethod" : "_CHANGEME_",
  "grantType" : "_CHANGEME_",
  "useBasicAuthForOauthTokenNeg" : false,
  "boxSubjectType" : "_CHANGEME_",
  "boxSubjectId" : "_CHANGEME_"
  "rateLimit": "_CHANGEME_"
}

serviceUri

The Box API hostname. In most cases it should be https://api.box.com/2.0.

tokenEndpoint

URL to obtain access tokens and refresh tokens. In most cases it should be https://api.box.com/oauth2/token.

clientId

The Box Application Client ID. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > Configuration > OAuth 2.0 Credentials > Client ID.

clientSecret

The Box Application Secret Key. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > Configuration > OAuth 2.0 Credentials > Client Secret.

acceptSelfSignedCertificates

The acceptSelfSignedCertificates option enables Box Sync to connect to Box servers that present self-signed digital certificates.

disableHostNameVerifier

The disableHostNameVerifier is a configuration option used to disable host name verification on HTTPS connections.

grantType

Parameter used within the OAuth 2.0 authorization flow to specify the type of grant being used to obtain an access token. The only value supported is client_credentials.

boxSubjectType

The Box Application SubjectType. User or Enterprise, according to availability. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > General Settings > UserID / EnterpriseID.

boxSubjectId

The Box Application User ID or Enterprise ID. It must match with the selected boxSubjectType. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > General Settings > UserID / EnterpriseID.

rateLimit

Limits how many requests the connector makes over a certain period of time. The default value is 1000 requests per minute (1000/min) as described in the Box Documentation. Additional examples: 997/min or 600/sec.

If throttling problems occur, this guide can be helpful:

Improve reconciliation query performance

Test the Box connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
'http://localhost:8080/openidm/system/box?_action=test'
{
  "name": box,
  "enabled": true,
  "config": "config/provisioner.openicf/box",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.box-connector",
    "connectorName": "org.forgerock.openicf.connectors.box.BoxConnector"
  },
  "displayName": "org.forgerock.openicf.connectors.box.BoxConnector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly and can authenticate to the Box server.

Box remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Box connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Box connector from here.

Refer to Remote connectors for configuring the Box remote connector.

Use the Box connector

You can use the Box connector to perform the following actions on a Box account.

Users

Create a Box user

This example creates a Box user with the minimum required attributes.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "__NAME__": "Jane Doe",
  "login": "janeDoe@example.com"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__'
{
  "_id": "34383152830",
  "hostname": "https://app.box.com/",
  "__NAME__": "Jane Doe",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "",
  "space_amount": "1.000000456753152E15",
  "phone": "",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "janedoe@nexter.net",
  "avatar_url": "https://app.box.com/api/avatar/large/34721687671",
  "role": "user",
  "address": "",
  "is_platform_access_only": "false"
}

When you create a new user, you must specify at least the login and __NAME__ attributes. The login attribute is typically the user’s email address.

Create a Box full user

This example creates a Box full user.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Designer",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": ["20013904637", "20013904699"],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos Buenos Aires",
  "is_platform_access_only": "false"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Designer",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos, Buenos Aires",
  "is_platform_access_only": "false"
}

Attribute limitations:

job_title: Max length 100.
phone: Max length 100.
address: Max length 255.
language: The language of the user, formatted in a modified version of the ISO 639-1 format.
role: The user’s enterprise role. Value is coadmin or user.
status: Value is one of active, inactive, cannot_delete_edit, cannot_delete_edit_upload.
space_amount: (int64) The user’s total available space in bytes. Set this to -1 to indicate unlimited storage.
timezone: The user’s timezone. Example: "Africa/Bujumbura".

List all Box users

This example queries all Box users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__?_queryFilter=True'
{
  "result": [
    {
      "_id": "34383152830",
      "hostname": "https://app.box.com/",
      "__NAME__": "Jane Doe",
      "is_exempt_from_device_limits": "false",
      "type": "user",
      "job_title": "",
      "space_amount": "1.000000456753152E15",
      "phone": "",
      "status": "active",
      "enterprise": [
        {
          "type": "enterprise",
          "id": "1162568706",
          "name": "testing"
        }
      ],
      "can_see_managed_users": "true",
      "is_external_collab_restricted": "false",
      "external_app_user_id": null,
      "is_exempt_from_login_verification": "false",
      "is_sync_enabled": "true",
      "groups": [],
      "max_upload_size": "5.36870912E10",
      "language": "en",
      "login": "janedoe@nexter.net",
      "avatar_url": "https://app.box.com/api/avatar/large/34383152830",
      "role": "user",
      "address": "",
      "is_platform_access_only": "false"
    },
    ...
    {
      "_id": "34721853021",
      "hostname": "https://app.box.com/",
      "__NAME__": "Miguel Benitez",
      "is_exempt_from_device_limits": "false",
      "type": "user",
      "job_title": "Designer",
      "space_amount": "1.000000456753152E15",
      "phone": "578945621",
      "status": "active",
      "enterprise": [
        {
          "type": "enterprise",
          "id": "1162568706",
          "name": "testing"
        }
      ],
      "can_see_managed_users": "true",
      "is_external_collab_restricted": "false",
      "external_app_user_id": null,
      "is_exempt_from_login_verification": "false",
      "is_sync_enabled": "true",
      "groups": ["20013904637", "20013904699"],
      "max_upload_size": "5.36870912E10",
      "language": "en",
      "login": "someone@example.com",
      "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
      "role": "user",
      "address": "San Carlos, Buenos Aires",
      "is_platform_access_only": "false"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyJ0eXBlIjoiaWQiLCJkaXIiOiJuZXh0IiwidGFpbCI6IjM0NzIxODUzMDIxIn0",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

For pagedResultsCookie, the last page returned is empty.
startsWith for __NAME__ is the only filter available.

List all Box user IDs

This example queries all Box users by their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__?_queryId=query-all-ids'
{
  "result": [
    {
      "_id": "32996521506"
    },
    ...
    {
      "_id": "34721853021"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyJ0eXBlIjoiaWQiLCJkaXIiOiJuZXh0IiwidGFpbCI6IjM0NzIxODUzMDIxIn0",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Get Box user

The following command queries a specific Box user by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos, Buenos Aires",
  "is_platform_access_only": "false"
}

Update a Box user

The following command updates a specific Box user by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request PUT \
--data '{
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Web Developer",
  "space_amount": "1.000000456753152E15",
  "phone": "1157199024",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [agregarle el grupo que esta arriba],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "Puerto La Cruz P.R",
  "is_platform_access_only": "false"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Web Developer",
  "space_amount": "9.99999999999999E14",
  "phone": "1157199024",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "Puerto La Cruz, P.R",
  "is_platform_access_only": "false"
}

If the target user’s email is not confirmed, you can’t change the primary login email address.

Delete a Box user

The following example deletes a Box user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request DELETE \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "is_platform_access_only": "false",
  "is_sync_enabled": "true",
  "avatar_url": "https://app.box.com/api/avatar/large/34740572881",
  "hostname": "https://app.box.com/",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "type": "user",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "max_upload_size": "5.36870912E10",
  "__NAME__": "Miguel Benitez",
  "space_amount": "9.99999999999999E14",
  "language": "en",
  "is_external_collab_restricted": "false",
  "address": "Puerto La Cruz, P.R",
  "can_see_managed_users": "true",
  "job_title": "Web Developer",
  "is_exempt_from_device_limits": "false",
  "status": "active",
  "role": "user",
  "phone": "1157199024",
  "login": "someone@example.com"
}

The response returns the user object before deletion.

GROUPS

Create a Box group

This example creates a Box group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "type": "group",
  "description": "Support Group - as imported from Active Directory",
  "external_sync_identifier": "AD:123456",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "permissions": {
    "can_invite_as_collaborator": true
  },
  "provenance": "Active Directory"
}' \
'http://localhost:8080/openidm/system/Box/__GROUP__'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

Query all Box groups

This example queries all Box groups:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__GROUP__?_queryFilter=True'
{
  "result": [
    {
      "_id": "20005069402",
      "provenance": null,
      "description": "generic_description",
      "group_type": "managed_group",
      "invitability_level": "all_managed_users",
      "member_viewability_level": "all_managed_users",
      "__NAME__": "A_20240611161336713",
      "type": "group",
      "external_sync_identifier": null
    },
    ...
    {
      "_id": "20147818911",
      "provenance": "Active Directory",
      "description": "Support Group - as imported from Active Directory",
      "group_type": "managed_group",
      "invitability_level": "admins_only",
      "member_viewability_level": "admins_only",
      "__NAME__": "Support",
      "type": "group",
      "external_sync_identifier": "AD:123456"
    }
  ],
  "resultCount": 22,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Get a Box group

This example gets a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

Update a Box group

This example updates a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request PUT \
--data '{
  "type": "group",
  "description": "Support Group - as imported from Active Directory",
  "external_sync_identifier": "AD:123456",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "name": "Support",
  "permissions": {
    "can_invite_as_collaborator": true
  },
  "provenance": "Active Directory"
}' \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

Other fields you can update are:

invitability_level: Specifies who can invite the group to collaborate on folders. Available values:
- admins_only
- admins_and_members
- all_managed_users
member_viewability_level: Specifies who can see the members of the group. Available values:
- admins_only
- admins_and_members
- all_managed_users
provenance: Max length 255

Delete a Box group

This example deletes a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request DELETE \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

The response returns the group object before deletion.

Mapping

From Box users to IDM users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`id`	`userId`	N/A
`__NAME__`	`UserName`	N/A
`enterprise`	`enterprise`	N/A
`external_app_user_id`	`external_app_user_id`	N/A
`login`	`mail`	N/A
`type`	`type`	N/A
`address`	`address`	N/A
`avatar_url`	`avatar_url`	N/A
`can_see_managed_users`	`can_see_managed_users`	N/A
`hostname`	`hostname`	N/A
`is_exempt_from_device_limits`	`is_exempt_from_device_limits`	N/A
`is_exempt_from_login_verification`	`is_exempt_from_login_verification`	N/A
`job_title`	`job_title`	N/A
`phone`	`phone`	N/A
`space_amount`	`space_amounts`	N/A
`max_upload_size`	`max_upload_size`	N/A
`language`	`language`	N/A
`status`	`status`	N/A
`memberof`	`memberof`	N/A
`is_sync_enabled`	`is_sync_enabled`	N/A
`is_external_collab_restricted`	`is_external_collab_restricted`	N/A
`is_platform_access_only`	`is_platform_access_only`	N/A
`role`	`role`	N/A

id

userId

N/A

__NAME__

UserName

N/A

enterprise

N/A

external_app_user_id

N/A

login

mail

N/A

type

N/A

address

N/A

avatar_url

N/A

can_see_managed_users

N/A

hostname

N/A

is_exempt_from_device_limits

N/A

is_exempt_from_login_verification

N/A

job_title

N/A

phone

N/A

space_amount

space_amounts

N/A

max_upload_size

N/A

language

N/A

status

N/A

memberof

N/A

is_sync_enabled

N/A

is_external_collab_restricted

N/A

is_platform_access_only

N/A

role

N/A

From IDM users to Box users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE

TARGET

TRANSFORMATION SCRIPT

userId

id

N/A

UserName

__NAME__

N/A

enterprise

N/A

external_app_user_id

N/A

mail

login

N/A

type

N/A

address

N/A

avatar_url

N/A

can_see_managed_users

N/A

hostname

N/A

is_exempt_from_device_limits

N/A

is_exempt_from_login_verification

N/A

job_title

N/A

phone

N/A

space_amount

space_amounts

N/A

max_upload_size

N/A

language

N/A

status

N/A

memberof

N/A

is_sync_enabled

N/A

is_external_collab_restricted

N/A

is_platform_access_only

N/A

role

N/A

From Box groups to IDM groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`_id`	`_id`	N/A
`__NAME__`	`groupName`	N/A
`group_type`	`group_type`	N/A
`invitability_level`	`invitability_level`	N/A
`permissions`	`can_invite_as_collaborator`	`source.can_invite_as_collaborator`
`external_sync_identifier`	`external_sync_identifier`	N/A
`provenance`	`provenance`	N/A
`description`	`description`	N/A
`member_viewability_level`	`member_viewability_level`	N/A
`type`	`type`	N/A

_id

N/A

__NAME__

groupName

N/A

group_type

N/A

invitability_level

N/A

permissions

can_invite_as_collaborator

source.can_invite_as_collaborator

external_sync_identifier

N/A

provenance

N/A

description

N/A

member_viewability_level

N/A

type

N/A

From IDM groups to Box groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`groupName`	`__NAME__`	N/A
`group_type`	`group_type`	N/A
`_id`	`_id`	N/A
`invitability_level`	`invitability_level`	N/A
`can_invite_as_collaborator`	`permissions`	`source.can_invite_as_collaborator`
`external_sync_identifier`	`external_sync_identifier`	N/A
`provenance`	`provenance`	N/A
`description`	`description`	N/A
`member_viewability_level`	`member_viewability_level`	N/A
`type`	`type`	N/A

groupName

__NAME__

N/A

group_type

N/A

_id

N/A

invitability_level

N/A

can_invite_as_collaborator

permissions

source.can_invite_as_collaborator

external_sync_identifier

N/A

provenance

N/A

description

N/A

member_viewability_level

N/A

type

N/A

OpenICF Interfaces Implemented by the Box.com Connector

The Box.com Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

Box.com Connector Configuration

The Box.com Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`serviceUri`	`String`	`null`		Yes
The service endpoint URI.
`boxSubjectType`	`String`	`null`		Yes
Description is not available
`login`	`String`	`null`		Yes
The service login name.
`boxSubjectId`	`String`	`null`		Yes
Description is not available
`password`	`GuardedString`	`null`	Yes	No
The service user password.
`rateLimit`	`String`	`null`		Yes
Description is not available
`authenticationMethod`	`String`	`OAUTH`		Yes
Defines which method is to be used to authenticate on the remote server. Options are BASIC (username/password), OAUTH (Client id/secret) or TOKEN (static token).
`tokenEndpoint`	`String`	`null`		No
When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token).
`clientId`	`String`	`null`		Yes
Client Id of the application registered at Box.com.
`clientSecret`	`GuardedString`	`null`	Yes	No
Client Secret of the application registered at Box.com.
`authToken`	`GuardedString`	`null`	Yes	No
Static authentication token.
`acceptSelfSignedCertificates`	`boolean`	`false`		Yes
To be used for debug/test purposes. To be avoided in production.
`disableHostNameVerifier`	`boolean`	`false`		Yes
To be used for debug/test purposes. To be avoided in production.
`disableHttpCompression`	`boolean`	`false`		Yes
Content compression is enabled by default. Set this property to true to disable it.
`clientCertAlias`	`String`	`null`		Yes
If TLS Mutual Auth is needed, set this to the certificate alias from the keystore.
`clientCertPassword`	`GuardedString`	`null`	Yes	Yes
If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password.
`maximumConnections`	`Integer`	`10`		Yes
Defines the max size of the HTTP connection pool used.
`httpProxyHost`	`String`	`null`		Yes
Defines the Hostname if an HTTP proxy is used between the connector and the service.
`httpProxyPort`	`Integer`	`null`		Yes
Defines the Port if an HTTP proxy is used between the connector and the service.
`httpProxyUsername`	`String`	`null`		Yes
Defines Proxy Username if an HTTP proxy is used between the connector and the service.
`httpProxyPassword`	`GuardedString`	`null`	Yes	Yes
Defines Proxy Password if an HTTP proxy is used between the connector and the service.
`connectionTimeout`	`int`	`30`		No
Defines a timeout for the underlying HTTP connection in seconds.
`refreshToken`	`GuardedString`	`null`		No
A refresh token retrieved in the final leg of OAuth 2. In most cases these are valid for 60 days, or until used.
`grantType`	`String`	`null`		No
The OAuth2 grant type to use (client_credentials or refresh_token).
`scope`	`String`	`null`		No
The OAuth2 scope to use.
`authorizationTokenPrefix`	`String`	`Bearer`		No
The prefix to be used in the Authorization HTTP header for Token authentication.
`useBasicAuthForOauthTokenNeg`	`boolean`	`true`		Yes
The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

serviceUri

String

null

Yes

The service endpoint URI.

boxSubjectType

String

null

Yes

Description is not available

login

String

null

Yes

The service login name.

boxSubjectId

String

null

Yes

Description is not available

password

GuardedString

null

Yes

The service user password.

rateLimit

String

null

Yes

Description is not available

authenticationMethod

String

OAUTH

Yes

Defines which method is to be used to authenticate on the remote server. Options are BASIC (username/password), OAUTH (Client id/secret) or TOKEN (static token).

tokenEndpoint

String

null

When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token).

clientId

String

null

Yes

Client Id of the application registered at Box.com.

clientSecret

GuardedString

null

Yes

Client Secret of the application registered at Box.com.

authToken

GuardedString

null

Yes

Static authentication token.

acceptSelfSignedCertificates

boolean

false

Yes

To be used for debug/test purposes. To be avoided in production.

disableHostNameVerifier

boolean

false

Yes

To be used for debug/test purposes. To be avoided in production.

disableHttpCompression

boolean

false

Yes

Content compression is enabled by default. Set this property to true to disable it.

clientCertAlias

String

null

Yes

If TLS Mutual Auth is needed, set this to the certificate alias from the keystore.

clientCertPassword

GuardedString

null

Yes

If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password.

maximumConnections

Integer

10

Yes

Defines the max size of the HTTP connection pool used.

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

A refresh token retrieved in the final leg of OAuth 2. In most cases these are valid for 60 days, or until used.

grantType

String

null

The OAuth2 grant type to use (client_credentials or refresh_token).

scope

String

null

The OAuth2 scope to use.

authorizationTokenPrefix

String

Bearer

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

Yes

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

⁽¹⁾ Whether the property value is considered confidential, and is therefore encrypted in IDM.

⁽²⁾ A list of operations in this column indicates that the property is required for those operations.

ICF 1.5.20.26

Box connector

Before you start

Install the Box connector

Configure the Box connector

Test the Box connector

Box remote connector

Use the Box connector

Users

Create a Box user

Create a Box full user

List all Box users

List all Box user IDs

Get Box user

Update a Box user

Delete a Box user

GROUPS

Create a Box group

Query all Box groups

Get a Box group

Update a Box group

Delete a Box group

Mapping

OpenICF Interfaces Implemented by the Box.com Connector

Box.com Connector Configuration

Basic Configuration Properties