--- title: Dropbox connector description: Create a Dropbox developer account. component: openicf page_id: openicf:connector-reference:dropbox canonical_url: https://docs.pingidentity.com/openicf/connector-reference/dropbox.html section_ids: before_you_start: Before you start install_the_dropbox_connector: Install the Dropbox connector configure_the_dropbox_connector: Configure the Dropbox connector config-connection-pooling-dropbox: Configure connection pooling mapping: Mapping test_the_dropbox_connector: Test the Dropbox connector members: MEMBERS invite_a_member: Invite a member get_members: Get members get_member: Get member get_member_email: Get member email delete_member: Delete member groups: GROUPS create_a_new_empty_group: Create a new empty group get_groups: Get groups update_a_group: Update a group delete_a_group: Delete a group roles: ROLES implemented-interfaces-org-forgerock-openicf-connectors-dropbox-DropboxConnector-1.5.20.34: OpenICF Interfaces Implemented by the Dropbox Connector config-properties-org-forgerock-openicf-connectors-dropbox-DropboxConnector-1.5.20.34: Dropbox Connector Configuration basic-configuration-properties-org-forgerock-openicf-connectors-dropbox-DropboxConnector-1.5.20.34: Basic Configuration Properties --- # Dropbox connector | | | | - | ------------------------------------------------------------ | | | This is a [SaaS common connector](preface.html#saas-common). | ## Before you start 1. Create a [Dropbox developer account](https://www.dropbox.com/developers/). 2. Create a new application with full Dropbox access. Add the required read and write permissions for team, member, and group. Remember to save the app key and app secret. 3. Get a [refresh token](https://developers.dropbox.com/oauth-guide). ## Install the Dropbox connector | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To check for an Advanced Identity Cloud application for this connector, refer to:- [Application management](https://docs.pingidentity.com/pingoneaic/latest/app-management/applications.html) - [App catalog](https://docs.pingidentity.com/pingoneaic/latest/app-management/app-catalog.html) | You can download any connector from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors), 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 | | ----------------------- | ----------------------- | ----------------------- | | [Dropbox](dropbox.html) | [icon: times, set=fa]No | [icon: times, set=fa]No | Download the connector .jar file from [Backstage](https://backstage.forgerock.com/downloads/browse/idm/featured/connectors). * If you're running the connector locally, place it in the `/path/to/openidm/connectors` directory, for example: ``` mv ~/Downloads/dropbox-connector-1.5.20.34.jar /path/to/openidm/connectors/ ``` * If you're 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: 1. From the navigation bar, click Configure > Connectors. 2. On the Connectors page, click New Connector. 3. On the New Connector page, type a Connector Name. 4. From the Connector Type list, select Dropbox Connector - 1.5.20.34. 5. Complete the Base Connector Details and any applicable Additional Options. | | | | - | -------------------------------------------------------------------------------------------------------------------- | | | For a list of all configuration properties, refer to [Dropbox Connector Configuration](#dropbox-config-prop-ezLink). | 6. Click Save. When your connector is configured correctly, the connector displays as Active in the admin UI. Refer to [this procedure](configure-connector.html#connector-wiz-REST) to create a connector configuration over REST. > **Collapse: 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`. > **Collapse: Authentication** > > * `Token Endpoint`: https\://api.dropboxapi.com/oauth2/token > > * `Client ID`: Your Client ID. > > * `Client Secret`: Your Client Secret. > > * `Refresh Token`: Your Refresh Token. > **Collapse: Object Types** > > If necessary, add or edit your object types to have these three objects with their properties: > > > **Collapse: ** > > > > | 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 | > > > **Collapse: ** > > > > | 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 | > > > **Collapse: Role** > > > > | PROPERTY NAME | TYPE | NATIVE TYPE | REQUIRED | > > | ------------- | ------ | ----------- | -------- | > > | `name` | String | String | NO | > > | `description` | String | String | NO | > > | `_id` | String | String | NO | 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`. > **Collapse: Sample Configuration** > > ```json > { > "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`. | ### Configure connection pooling The Dropbox connector supports [HTTP pooling](pooling.html#http-pooling), which can substantially improve the performance of the connector. Learn more about the basic connection pooling configuration and different pooling mechanisms described in [Connection pooling configuration](pooling.html). ## Mapping > **Collapse: From Dropbox users to OpenIDM Users** > > Attributes Grid > > | 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 | > > Association>Association Rules>Correlation Queries > > * Link Qualifier: default > > * Any of the following fields: `mail` > **Collapse: From OpenIDM Users to Dropbox Users** > > Attributes Grid > > | SOURCE | TARGET | TRANSFORMATION SCRIPT | > | ----------- | ------------ | --------------------- | > | `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` > **Collapse: 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 | > | ----------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------- | > | `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 | > > Association>Association Rules>Correlation Queries > > * Link Qualifier: default > > * Any of the following fields: `groupExternalId` > **Collapse: From OpenIDM Groups to Dropbox groups** > > Attributes Grid > > | 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 | > > 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's 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](#roles): ``` 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](interfaces.html): * 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: ### Basic Configuration Properties | Property | Type | Default | Encrypted(1) | Required(2) | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------- | ------------------------ | ------------------------- | | `serviceUri` | `String` | `null` | | [icon: check, set=fas]Yes | | The Dropbox endpoint URI. | | | | | | `login` | `String` | `null` | | [icon: check, set=fas]Yes | | The Dropbox login name. | | | | | | `password` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | The Dropbox user password. | | | | | | `authenticationMethod` | `String` | `OAUTH` | | [icon: check, set=fas]Yes | | Defines which method is to be used to authenticate on the remote server. Options are `BASIC` (username/password), `OAUTH` (Client id/secret), `JWT_TOKEN` (jwt token), or `TOKEN` (static token). | | | | | | `tokenEndpoint` | `String` | `null` | | [icon: times, set=fas]No | | When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (). | | | | | | `clientId` | `String` | `null` | | [icon: check, set=fas]Yes | | The client identifier for OAuth2. | | | | | | `clientSecret` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | Secure client secret for OAuth2. | | | | | | `authToken` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: times, set=fas]No | | Static authentication token. | | | | | | `acceptSelfSignedCertificates` | `boolean` | `false` | | [icon: check, set=fas]Yes | | To be used for debug/test purposes. To be avoided in production. | | | | | | `disableHostNameVerifier` | `boolean` | `false` | | [icon: check, set=fas]Yes | | To be used for debug/test purposes. To be avoided in production. | | | | | | `disableHttpCompression` | `boolean` | `false` | | [icon: check, set=fas]Yes | | Set this property to `true` to disable content compression. | | | | | | `clientCertAlias` | `String` | `null` | | [icon: check, set=fas]Yes | | If TLS Mutual Auth is needed, set this to the certificate alias from the keystore. | | | | | | `clientCertPassword` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]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` | | [icon: check, set=fas]Yes | | Defines the max size of the HTTP connection pool used. | | | | | | `httpProxyHost` | `String` | `null` | | [icon: check, set=fas]Yes | | Defines the Hostname if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyPort` | `Integer` | `null` | | [icon: check, set=fas]Yes | | Defines the Port if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyUsername` | `String` | `null` | | [icon: check, set=fas]Yes | | Defines Proxy Username if an HTTP proxy is used between the connector and the service. | | | | | | `httpProxyPassword` | `GuardedString` | `null` | [icon: lock, set=fas]Yes | [icon: check, set=fas]Yes | | Defines Proxy Password if an HTTP proxy is used between the connector and the service. | | | | | | `connectionTimeout` | `int` | `30` | | [icon: times, set=fas]No | | Defines a timeout for the underlying HTTP connection in seconds. | | | | | | `refreshToken` | `GuardedString` | `null` | | [icon: times, set=fas]No | | Used by the refresh\_token grant type. | | | | | | `grantType` | `String` | `null` | | [icon: times, set=fas]No | | The OAuth2 grant type to use (`client_credentials`, `refresh_token`, or `jwt_bearer`). | | | | | | `scope` | `String` | `null` | | [icon: times, set=fas]No | | The OAuth2 scope to use. | | | | | | `authorizationTokenPrefix` | `String` | `Bearer` | | [icon: times, set=fas]No | | The prefix to be used in the Authorization HTTP header for Token authentication. | | | | | | `useBasicAuthForOauthTokenNeg` | `boolean` | `true` | | [icon: check, set=fas]Yes | | The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header). | | | | | | `jwtKey` | `String` | `null` | | [icon: times, set=fas]No | | The JWT data structure that represents a cryptographic key. | | | | | | `jwtExpiration` | `Integer` | `null` | | [icon: times, set=fas]No | | Defines the JWT expiration time in seconds. | | | | | | `jwtAlgorithm` | `String` | `null` | | [icon: times, set=fas]No | | The Algorithm type to sign payload. | | | | | | `jwtClaims` | `Map` | `null` | | [icon: times, set=fas]No | | JWT Claims to be included in the payload | | | | | | `jwtPem` | `String` | `null` | | [icon: times, set=fas]No | | The contents of the private key of the PEM file | | | | | | `jwtCert` | `String` | `null` | | [icon: times, set=fas]No | | The contents of the certificate of the PEM file | | | | | | `keyAlgorithm` | `String` | `null` | | [icon: times, set=fas]No | | Indicates the type of key (such as RSA, DSA or EC) used to sign from the PEM. | | | | | (1) Whether the property value is considered confidential, and is therefore encrypted in IDM. (2) A list of operations in this column indicates that the property is required for those operations.