ICF 1.5.20.26

Dropbox connector

Before you start

  1. Create a Dropbox developer account.

  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.

Install the Dropbox 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

Dropbox

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/dropbox-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 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 drop-down list, select Dropbox Connector - 1.5.20.26.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Dropbox Connector Configuration

  6. 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

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
__GROUP__
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
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.

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

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

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

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

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 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:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

serviceUri

String

null

Yes

The Dropbox endpoint URI.

login

String

null

Yes

The Dropbox login name.

password

GuardedString

null

Yes

No

The Dropbox user password.

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

The client identifier for OAuth2.

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2.

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

Used by the refresh_token grant type.

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).

(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.