Dropbox Connector

Before you start

Create an account in: https://www.dropbox.com/developers.
Create a new application with the full Dropbox access type. Add the required read and write permissions for team, member, and group. Remember to save the app key and app secret.
Get a refresh token.

Install the Dropbox connector

Some connectors are bundled with Identity Cloud, IDM, or RCS by default. In these cases, you can skip the installation process and move directly to configuring your connector.

Bundle availability
Connector	Identity Cloud	IDM	RCS
Dropbox Connector	No	No	No

Download the connector .jar file from the ForgeRock BackStage download site.

If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:
```
mv ~/Downloads/dropbox-connector-1.5.20.15.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 Dropbox 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 Dropbox Connector - 1.5.20.15.
Complete the Base Connector Details.

For a list of all configuration properties, refer to Dropbox 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.

Base Connector Details

Dropbox Endpoint : https://api.dropboxapi.com/2
Use Basic Auth For OAuth Token Neg : true | false
Max connections: max size of the http connection pool used. Defaults to 10.
Connection Timeout (seconds): Defines a timeout for the underlying http connection in seconds. Defaults to 30.

Authentication

Token Endpoint: https://api.dropboxapi.com/oauth2/token
Client ID: Your Client ID.
Client Secret: Your Client Secret.
Refresh Token: Your Refresh Token.

Object Types

If necessary, add or edit your object types to have these three objects with their properties:

__ACCOUNT__

PROPERTY NAME TYPE NATIVE TYPE REQUIRED

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
`team_member_id`	String	String	NO
`given_name`	String	String	NO
`surname`	String	String	NO
`email`	String	String	YES
`member_status`	String	String	NO
`membership_type`	String	String	NO
`role_id`	String	String	NO
`email_verified`	Boolean	Boolean	NO
`invited_on`	String	String	NO
`groups`	Array	Object	NO
`secondary_emails`	Array	String	NO
`abbreviated_name`	String	String	NO
`joined_on`	String	String	NO

team_member_id

String

given_name

String

surname

String

email

String

YES

member_status

String

membership_type

String

role_id

String

email_verified

Boolean

invited_on

String

groups

Array

Object

secondary_emails

Array

String

abbreviated_name

String

joined_on

String

__GROUP__

PROPERTY NAME TYPE NATIVE TYPE REQUIRED

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
`group_id`	String	String	NO
`group_name`	String	String	YES
`group_external_id`	String	String	YES
`members`	Array	Object	NO
`group_management_type`	String	String	NO
`member_count`	Integer	Integer	NO

group_id

String

group_name

String

YES

group_external_id

String

YES

members

Array

Object

group_management_type

String

member_count

Integer

Role

PROPERTY NAME TYPE NATIVE TYPE REQUIRED

PROPERTY NAME	TYPE	NATIVE TYPE	REQUIRED
`name`	String	String	NO
`description`	String	String	NO
`_id`	String	String	NO

name

String

description

String

_id

String

If configuring the connector over REST or through the filesystem, specify the connection details to the Dropbox resource provider in the configurationProperties for the connector. If you are using OAuth for your connection, the minimum required properties are serviceUri, tokenEndpoint, refreshToken, clientId, and clientSecret.

Sample Configuration

{
    "configurationProperties" : {
        "tokenExpiration" : null,
        "accessToken" : null,
        "serviceUri" : "https://api.dropboxapi.com/2",
        "login" : null,
        "password" : null,
        "authenticationMethod" : "OAUTH",
        "tokenEndpoint" : "https://api.dropboxapi.com/oauth2/token",
        "clientId" : "k3..........5g",
        "clientSecret" : "xxxxxxxxxxxxxxxxxx",
        "refreshToken" : "xxxxxxxxxxxxxxxxxx",
        "authToken" : null,
        "acceptSelfSignedCertificates" : false,
        "disableHostNameVerifier" : false,
        "disableHttpCompression" : false,
        "clientCertAlias" : null,
        "clientCertPassword" : null,
        "maximumConnections" : "10",
        "httpProxyHost" : null,
        "httpProxyPort" : null,
        "httpProxyUsername" : null,
        "httpProxyPassword" : null,
        "connectionTimeout" : "30",
        "grantType" : null,
        "scope" : null,
        "authorizationTokenPrefix" : "Bearer",
        "useBasicAuthForOauthTokenNeg" : true
    }
}

On startup, IDM encrypts the value of the clientSecret.

Mapping

From Dropbox users to OpenIDM Users

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`team_member_id`	`teamMemberId`	N/A
`email`	`mail`	N/A
`surname`	`sn`	N/A
`given_name`	`givenName`	N/A
`member_status`	`memberStatus`	N/A
`membership_type`	`membershipType`	N/A
`email_verified`	`emailVerified`	N/A
`groups`	`groups`	N/A
`secondary_emails`	`secondaryEmails`	N/A
`member_status`	`memberStatus`	N/A

team_member_id

teamMemberId

N/A

email

mail

N/A

surname

sn

N/A

given_name

givenName

N/A

member_status

memberStatus

N/A

membership_type

membershipType

N/A

email_verified

emailVerified

N/A

groups

N/A

secondary_emails

secondaryEmails

N/A

member_status

memberStatus

N/A

Association>Association Rules>Correlation Queries

Link Qualifier: default
Any of the following fields: mail

From OpenIDM Users to Dropbox Users

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`givenName`	`given_name`	N/A
`sn`	`surname`	N/A
`mail`	`email`	N/A
`roleId`	`role_id`	N/A

givenName

given_name

N/A

sn

surname

N/A

mail

email

N/A

roleId

role_id

N/A

Association>Association Rules>Correlation Queries

Link Qualifier: default
Any of the following fields: email

From Dropbox groups to OpenIDM Groups

When a member is added or removed from a group, it is necessary to perform a reconciliation from dropbox members to IDM members to keep the members of a group up to date.

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`group_name`	`groupName`	N/A
`members`	`members`	N/A
`member_count`	`memberCount`	N/A
`group_external_id`	`groupExternalId`	var result = source.group_external_id; if(result == undefined){ result = source.group_id; } result;
`group_management_type`	`groupManagementType`	N/A

group_name

groupName

N/A

members

N/A

member_count

memberCount

N/A

group_external_id

groupExternalId

var result = source.group_external_id;
if(result == undefined){
result = source.group_id;
}
result;

group_management_type

groupManagementType

N/A

Association>Association Rules>Correlation Queries

Link Qualifier: default
Any of the following fields: groupExternalId

From OpenIDM Groups to Dropbox groups

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

SOURCE	TARGET	TRANSFORMATION SCRIPT
`groupName`	`group_name`	N/A
`members`	`members`	N/A
`groupManagementType`	`group_management_type`	N/A
`groupExternalId`	`group_external_id`	N/A

groupName

group_name

N/A

members

N/A

groupManagementType

group_management_type

N/A

groupExternalId

group_external_id

N/A

Association>Association Rules>Correlation Queries

Link Qualifier: default
Any of the following fields: group_id, group_external_id

Test the Dropbox connector

Test that the connector was configured correctly:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request POST  'http://localhost:8080/system/Dropbox?_action=test'
{
    "name" : "Dropbox",
    "enabled" : true,
    "config" : "config/provisioner.openicf/Dropbox",
    "connectorRef" : {
        "bundleVersion" : [1.5.0.0,1.6.0.0),
        "bundleName" : "org.forgerock.openicf.connectors.dropbox-connector",
        "connectorName" : "org.forgerock.openicf.connectors.dropbox.DropboxConnector"
    },
    "displayName" : "Dropbox Connector",
    "objectTypes" : [
        "__GROUP__",
        "role",
        "__ACCOUNT__",
        "__ALL__"
    ],
    "ok" : true
}

MEMBERS

Invite a member

To invite a member, it is necessary to at least provide the email field. The fields given_name, surname, role_id are not required, but it is advisable to fill them in because these fields cannot be modified later. To get the list of roles go here:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Accept-API-Version: resource=1.0' \
--header 'Content-Type: application/json' \
--data '{
    "email" : "NEW.MEMBER@EMAIL.COM",
    "given_name" : "GIVENNAME",
    "surname" : "SURNAME",
    "role_id" : "ROLE ID"
}'
--request POST 'http://localhost:8080/system/Dropbox/__ACCOUNT__?_action=create'
{
    "_id" : "TEAM_MEMBER_ID",
    "role_id" : "ROLE_ID",
    "email" : "NEW.MEMBER@EMAIL.COM",
    ...
}

Get members

Retrieve a list of team members ids from Dropbox. The limit of results and the default value are 1000:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id" : "001"
        },
        {
            "_id" : "002"
        },
        {
            "_id" : "003"
        },
        ...
    ]
}

Get member

Retrieve a team member from Dropbox. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID'
{
    "_id" : "TEAM_MEMBER_ID",
    "groups" : [
        {
            "access_type" : "member",
            "group_id" : "GROUP_ID"
        }
    ],
    "email" : "test@email.com",
    "abbreviated_name" : "gs",
    "joined_on" : "2023-01-01T00:00:00Z",
    "surname" : "surname",
    "member_status" : "active",
    "email_verified" : true,
    "given_name" : "givenname",
    "membership_type" : "full",
    "role_id" : "ROLE_ID"
}

Get member email

Retrieve a team member in Dropbox filtering by email field. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID?_fields=email'
{
    "_id" : "TEAM_MEMBER_ID",
    "email" : "test@email.com"
}

Delete member

Delete a member from a team. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Accept-API-Version: resource=1.0' \
--request DELETE 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID'
{
    "_id" : "TEAM_MEMBER_ID",
    "email" : "deleted.member@email.com",
    ...
}

GROUPS

Create a new empty group

Group name must be provided at least when creating a new group. group_management_type can be user_managed or company_managed, default is company_managed.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Content-Type: application/json' \
--data '{
    "group_name" : "GROUP NAME",
    "group_management_type" : "company_managed",
    "group_external_id" : "GROUP EXTERNAL ID"
}'
--request POST 'http://localhost:8080/openidm/system/Dropbox/__GROUP__?_action=create' \
{
    "_id" : "_id",
    "group_id" : "GROUP_ID",
    "member_count" : 0,
    "group_name" : "GROUP NAME",
    "group_external_id" : "GROUP EXTERNAL ID",
    "group_management_type" : "company_managed",
    "members" : []
}

Get groups

Retrieves a list of groups showing only the ids. The limit of results and the default value are 1000:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__GROUP__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id" : "001"
        },
        {
            "_id" : "002"
        },
        {
            "_id" : "003",
        },
        ...
    ]
}

Update a group

The default group in Dropbox cannot be updated.

The fields that can be updated for a group are group_name, group_external_id, group_management_type (company_managed or user_managed). To add a member to a group, you need to provide the type of access and the team member id; to delete a member, delete the object. The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'If-Match: *' \
--header 'Content-Type: application/json' \
--data '{
    "group_name" : "new name",
    "group_management_type" : "company_managed",
    "group_external_id" : "new external id",
    "members" : [
        {
            "access_type" : "member",
            "team_member_id" : "TEAM_MEMBER_ID"
        }
    ]
}
--request PUT 'http://localhost:8080/openidm/system/Dropbox/__GROUP__/GROUP_ID'
{
    "group_id" : "GROUP_ID",
    "group_external_id" : "new extenal id",
    "group_name" : "new name",
    "member_count" : 1,
    "group_management_type" : "company_managed",
    "members" : [
        {
            "access_type" : "member",
            "team_member_id" : "TEAM_MEMBER_ID"
        }
    ]
}

Delete a group

The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Accept-API-Version: resource=1.0' \
--request DELETE 'http://localhost:8080/openidm/system/Dropbox/__GROUP__/GROUP_ID'
{
    "_id" : "GROUP_ID",
    "group_name" : "group name",
    ...
}

ROLES

Get available roles from Dropbox members.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/role/?_queryFilter=true'
{
    "result" : [
        {
            "_id" : "ROLE_ID",
            "name" : "Name role",
            "description" : "Description role"
        },
        ...
    ]
}

OpenICF Interfaces Implemented by the Dropbox Connector

The Dropbox 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.

Dropbox Connector Configuration

The Dropbox Connector has the following configurable properties:

Configuration properties

Property Type Default Encrypted⁽¹⁾ Required⁽²⁾

Property	Type	Default	Encrypted⁽¹⁾	Required⁽²⁾
`tokenExpiration`	`Long`	`null`		No
Description is not available
`accessToken`	`String`	`null`		No
Description is not available
`serviceUri`	`String`	`null`		Yes
Description is not available
`login`	`String`	`null`		Yes
Description is not available
`password`	`GuardedString`	`null`	Yes	No
Description is not available
`authenticationMethod`	`String`	`OAUTH`		Yes
Description is not available
`tokenEndpoint`	`String`	`null`		No
Description is not available
`clientId`	`String`	`null`		Yes
Description is not available
`clientSecret`	`GuardedString`	`null`	Yes	No
Description is not available
`authToken`	`GuardedString`	`null`	Yes	No
Description is not available
`acceptSelfSignedCertificates`	`boolean`	`false`		Yes
Description is not available
`disableHostNameVerifier`	`boolean`	`false`		Yes
Description is not available
`disableHttpCompression`	`boolean`	`false`		Yes
Description is not available
`clientCertAlias`	`String`	`null`		Yes
Description is not available
`clientCertPassword`	`GuardedString`	`null`	Yes	Yes
Description is not available
`maximumConnections`	`Integer`	`10`		Yes
Description is not available
`httpProxyHost`	`String`	`null`		Yes
Description is not available
`httpProxyPort`	`Integer`	`null`		Yes
Description is not available
`httpProxyUsername`	`String`	`null`		Yes
Description is not available
`httpProxyPassword`	`GuardedString`	`null`	Yes	Yes
Description is not available
`connectionTimeout`	`int`	`30`		No
Description is not available
`refreshToken`	`GuardedString`	`null`		No
Description is not available
`grantType`	`String`	`null`		No
Description is not available
`scope`	`String`	`null`		No
Description is not available
`authorizationTokenPrefix`	`String`	`Bearer`		No
Description is not available
`useBasicAuthForOauthTokenNeg`	`boolean`	`true`		Yes
Description is not available

tokenExpiration

Long

null

Description is not available

accessToken

String

null

Description is not available

serviceUri

String

null

Yes

Description is not available

login

String

null

Yes

Description is not available

password

GuardedString

null

Yes

Description is not available

authenticationMethod

String

OAUTH

Yes

Description is not available

tokenEndpoint

String

null

Description is not available

clientId

String

null

Yes

Description is not available

clientSecret

GuardedString

null

Yes

Description is not available

authToken

GuardedString

null

Yes

Description is not available

acceptSelfSignedCertificates

boolean

false

Yes

Description is not available

disableHostNameVerifier

boolean

false

Yes

Description is not available

disableHttpCompression

boolean

false

Yes

Description is not available

clientCertAlias

String

null

Yes

Description is not available

clientCertPassword

GuardedString

null

Yes

Description is not available

maximumConnections

Integer

10

Yes

Description is not available

httpProxyHost

String

null

Yes

Description is not available

httpProxyPort

Integer

null

Yes

Description is not available

httpProxyUsername

String

null

Yes

Description is not available

httpProxyPassword

GuardedString

null

Yes

Description is not available

connectionTimeout

int

30

Description is not available

refreshToken

GuardedString

null

Description is not available

grantType

String

null

Description is not available

scope

String

null

Description is not available

authorizationTokenPrefix

String

Bearer

Description is not available

useBasicAuthForOauthTokenNeg

boolean

true

Yes

Description is not available

⁽¹⁾ 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.15

Dropbox Connector

Before you start

Install the Dropbox connector

Configure the Dropbox connector

Mapping

Test the Dropbox connector

MEMBERS

Invite a member

Get members

Get member

Get member email

Delete member

GROUPS

Create a new empty group

Get groups

Update a group

Delete a group

ROLES

OpenICF Interfaces Implemented by the Dropbox Connector

Dropbox Connector Configuration

Configuration properties