Dropbox Connector Version 2.0 User Guide
2016 Ping Identity Corporation. All rights reserved. PingFederate Dropbox Connector User Guide Version 2.0 February, 2016 Ping Identity Corporation 1001 17th Street, Suite 100 Denver, CO 80202 U.S.A. Phone: 877.898.2905 (+1 303.468.2882 outside North America) Fax: 303.468.2909 Web Site: www.pingidentity.com Trademarks Ping Identity, the Ping Identity logo, PingFederate, PingOne, PingConnect, and PingEnable are registered trademarks of Ping Identity Corporation ("Ping Identity"). All other trademarks or registered trademarks are the property of their respective owners. Disclaimer The information provided in this document is provided "as is" without warranty of any kind. Ping Identity disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. In no event shall Ping Identity or its suppliers be liable for any damages whatsoever including direct, indirect, incidental, consequential, loss of business profits or special damages, even if Ping Identity or its suppliers have been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of liability for consequential or incidental damages so the foregoing limitation may not apply. Document Lifetime Ping Identity may occasionally update online documentation between releases of the related software. Consequently, if this PDF was not downloaded recently, it may not contain the most up-to-date information. Please refer to documentation.pingidentity.com for the most current information. From the Web site, you may also download and refresh this PDF if it has been updated, as indicated by a change in this date: February 23, 2016. PingFederate Dropbox Connector 2 User Guide
Contents Introduction... 4 Supported Features... 4 System Requirements... 4 ZIP Manifest... 4 Installation and Setup... 4 Getting Started... 4 Upgrading Existing Dropbox Connectors... 7 Installing the Connector... 8 Configuring Server Settings... 8 Configuring a Connection... 8 Complete Setup of SAML SSO to Dropbox... 11 Provisioning Groups to Dropbox... 12 Mapping Users to Groups... 13 Attribute Index... 13 PingFederate Dropbox Connector 3 User Guide
Introduction This document assumes you have read the Introduction section of the SaaS Connector User Guide. Supported Features Outbound User Provisioning Outbound Group Provisioning Ability to add Users to Groups Browser-based SP and IdP-initiated SSO System Requirements The Dropbox Connector requires installation of PingFederate 7.2.1 or higher. The Dropbox Connector may require the following endpoints to be whitelisted on the firewall to allow outbound connections: https://api.dropboxapi.com ZIP Manifest The distribution ZIP file for the Connector contains the following: ReadMeFirst.pdf contains links to this online documentation. saml-metadata.xml The metadata used for Browser SSO /legal: Legal.pdf copyright and license information. /dist contains libraries needed for the Connector: pf-dropbox-quickconnection-2.0.jar PingFederate Dropbox Connector Installation and Setup The following sections explain how to obtain the necessary information required for installing and configuring this SaaS Connector. Please follow these sections completely and in order. Getting Started Before you can configure this Connector, you will need to complete the following steps. Tip: Some of the following steps result in information to be used at a later time in this User Guide. It is recommended that you copy this information to a secure location to reference in later steps. PingFederate Dropbox Connector 4 User Guide
Obtain Your OAuth 2.0 Access Token The Dropbox Connectors Outbound Provisioning functionality is built using Dropbox s REST API, which requires an OAuth 2.0 access token for authentication. To obtain the access token, you will need to first obtain an app key and secret from Dropbox. To Obtain Your App Key & Secret from Dropbox: 1. Log into Dropbox as an administrative user. 2. Go to My Apps for Dropbox. 3. Click the Create app button. Choose Dropbox Business API as the API to use. Choose Team member management as the type of access you need. Give your application a name, such as PingFederate Provisioning. Click the Create app button. 4. Copy the App Key and App secret values to use in the next section. 5. Add the following URL to the Redirect URIs: https://oauth.pingone.com/ocs/ppm/rest/v1/oauth/oastempcredresponse/ 6. (Optional) Click the Apply for production button to open your app to more users. Development status only allows your app to be accessed by up to 100 users. To Generate Your OAuth 2.0 Access Token: 1. Go to the Ping OAuth Configuration Service here. 2. Select Dropbox Connector from the drop down menu. 3. Enter the App Key you obtained above into the ClientID field. 4. Enter the App Secret you obtained above into the Client Secret field and click the Connect button. 5. Log in to Dropbox as an administrative user. PingFederate Dropbox Connector 5 User Guide
Note: If you are already signed in to Dropbox, you will not be asked to log in again. Please be sure that the account you are signed in under is an administrative account. 6. Click the Allow button to generate your Access Token. 7. Copy the Access Token to use when configuring the Dropbox Connector. Prepare the Dropbox SAML 2.0 Metadata XML This Connectors quick-connection template uses a metadata XML file to assist in configuring many settings in the SP Connection. When asked during the Connection configuration steps, import the saml-metadata.xml packaged with this connector. To prepare your saml-metadata.xml: 1. Open the saml-metadata.xml file contained with your connector with a text editor of your choice. 2. No changes are required, unless you have a SP connection already created with the same entity id. 3. Once you have updated the saml-metadata.xml file, save your changes. Synchronizing Existing Dropbox Users and Groups Important: If your Dropbox account already has Users or Groups you wish to provision with this connector, this is possible by following the steps below. To provision existing User accounts on Dropbox: Ensure that the value mapped to the Email attribute, (when configuring the connector) matches the existing Dropbox Users email exactly as it appears in Dropbox. For example, if on the Attribute Mapping screen, the User Email attribute is mapped to the User mail attribute in your LDAP. This will synchronize a User that already exists on Dropbox with an Email in Dropbox of jsmith@domain.com to the User in your LDAP who has a mail attribute value of jsmith@domain.com. PingFederate Dropbox Connector 6 User Guide
When the Dropbox connector provisions for the first time, this address will be used to synchronize the User in your LDAP data store with the User in Dropbox. To provision existing Groups on Dropbox: LDAP Groups will be synched with existing Groups on Dropbox that have the same name. For example, if a group in LDAP is named Accounting and is targeted for provisioning, if a group named Accounting already exists in Dropbox, the two will be synchronized. Any users that are members of the Accounting group in LDAP that have been provisioned by the connector will become members of the Accounting group in Dropbox. Likewise, any users that are members of the Accounting group in Dropbox but are not members of the Accounting group in LDAP will be removed from that group in Dropbox. Upgrading Existing Dropbox Connectors 1. Before stopping the PingFederate server to upgrade the Dropbox Connector, access the Attribute Mapping screen for existing channel configurations and note the current configuration. Warning: The upgrade process may remove existing mappings and defaults on the Attribute Mapping screen. These may need to be reconfigured again before activating the channel configuration. 2. Disable the existing SP Connection where the Dropbox Connector is configured. 3. Delete the existing Dropbox Connector SP Connection and save. 4. Stop the PingFederate server if it is running. 5. Unzip the Dropbox Connector distribution ZIP file into a holding directory. 6. Remove any versions of pf-dropbox-quickconnection-.x.jar from: <pf_install>/pingfederate/server/default/deploy 7. Also remove the following files from the same directory if they are present: pf-dropbox-oauth-helper.war gson-2.2.4.jar 8. From the dist directory of the new version of the connector, copy the files: pf-dropbox-quickconnection-2.0.jar into the directory: <pf_install>/pingfederate/server/default/deploy Important: Make sure to remove existing versions of Dropbox Connector files. 9. Start the PingFederate server. 10. Create a new SP Connection, using Dropbox as the Connection Template. PingFederate Dropbox Connector 7 User Guide
11. Follow the instructions in the Configuring a Connection section below in order to configure Metadata, and OAuth. 12. Access the Attribute Mapping for existing channel configurations and click Refresh Fields. 13. Ensure all new required fields (if any), are mapped appropriately or have a default value. 14. Once completed with the attribute configuration, click Done, Done, and Save. 15. Activate the SP Connection to resume Outbound Provisioning. Installing the Connector To install the Dropbox Connector, please follow the instructions in the Installing the Connector section of the SaaS Connector User Guide. Note: Do not delete any versions of the Common Provisioning Layer (prov-cplx.x.x.jar) from the deploy folder that are required for other SaaS Connectors. Configuring Server Settings To configure Server Settings in preparation of configuring the Dropbox Connector, please follow the instructions in the Configuring Server Settings section of the SaaS Connector Guide). Configuring a Connection Important: This section directs you to the SaaS Connector User Guide for most of the steps to configure this Connector but contains additional steps that need to be followed to successfully configure this Connector. Ensure you follow the additional steps below as directed. To Configure a Connection using the Dropbox Connector, please follow the instructions in the Configuring a Connection section of the SaaS Connector User Guide, making the adjustments listed in the following section. Additional Steps On the Connection Template screen, select Dropbox Connector as the Connection Template to use for this SP Connection. You will be asked to provide the saml-metadata.xml file you obtained earlier in the Getting Started section of this User Guide. PingFederate Dropbox Connector 8 User Guide
On the General Info screen, the default values are taken from the metadata file you selected in an earlier step. We recommend using these default values. (SSO Configuration) On the SAML Profiles screen, ensure that the IdP-Initiated SSO and SP- Initiated SSO profiles are selected and click Next. PingFederate Dropbox Connector 9 User Guide
(SSO Configuration) On the Attribute Contract screen, ensure that the SAML_SUBJECT name format is set to urn:oasis:names:tc:saml:1.1:nameid-format:emailaddress. (SSO Configuration) On the Allowable SAML Bindings screen, ensure that the POST and Redirect profiles are selected (de-select Artifact and SOAP) and click Next. (SSO Configuration) On the Signature Policy screen, ensure that the Always sign the SAML Assertion is selected and click Next. PingFederate Dropbox Connector 10 User Guide
On the Target screen when configuring provisioning, enter the Access Token value you obtained in the Obtain Your OAuth 2.0 Access Token section of this User Guide into the OAUTH ACCESS TOKEN field and click Done. Complete Setup of SAML SSO to Dropbox The following section describes the steps for configuring SP and IdP-initiated SSO to Dropbox. Note: This section requires two pieces of information that can be found within PingFederate. The first is the PingFederate SSO Application Endpoint, which can be found under on the SP Connection Activation & Summary page and the second is the exported certificate used to sign the SAML assertion (configured in step 11 of Configure a Connection). 1. Navigate to https://www.dropbox.com/team/admin/ and sign in with your Team Owner credentials. 2. Navigate to Authentication to view the Single sign-on section. 3. Select Enable single sign-on and select Optional or Required based on your SSO requirements. 4. Enter the PingFederate SSO Application endpoint into the Sign in URL field. https://<pf_host>:<pf_port>/idp/startsso.ping?partnerspid=<connection_id> where: <pf_host> is the machine running the PingFederate server. <pf_port> is the PingFederate port (default value: 9031). <connection_id> is the Connection ID of the SP connection (e.g. https://www.dropbox.com/). 5. Import the signing certificate into the X.509 certificate field. PingFederate Dropbox Connector 11 User Guide
6. Click Save Changes to complete the Dropbox SSO Setup. Once saved, emails will be sent to team members in order to instruct them on how to initiate logging in. Note: See this Dropbox help article for more information on how to setup SSO for Dropbox. Provisioning Groups to Dropbox The Connector enables an organization to provision and manage groups in Dropbox. Tip: For instructions on synching the connector with existing Dropbox groups, please refer to Synchronizing Existing Dropbox Users and Groups under the Getting Started section of this User Guide. Creating Groups To create a group, target a group in LDAP to be provisioned. The connector will create the group in Dropbox with the name of the group from LDAP. Updating Groups Renaming the group in LDAP will update the group s name in Dropbox. Deleting Groups PingFederate Dropbox Connector 12 User Guide
The Dropbox Connector supports the ability to delete groups from Dropbox. Deleting a group in LDAP will hard-delete the group in Dropbox on the next provisioning cycle. Warning: Deleting groups will permanently delete that group in Dropbox. This operation cannot be undone. Mapping Users to Groups The connector supports the ability to manage user s group memberships in Dropbox. A user can be a member of one or more groups. Adding a User to a Group Making a provisioned User a member of a provisioned Group in LDAP will also add that User to that Group in Dropbox. There are two ways to add a user to a group in LDAP: Invoke the user Properties from Active Directory Users and Computers and enter the group name in the Member Of tab. Invoke the group Properties from Active Directory Users and Computers and enter the user name in the Members tab. The user(s) will be added to the group(s) on the next provisioning cycle. Removing a User from a Group Removing a provisioned User from a provisioned Group in LDAP will remove that User from that Group in Dropbox. Attribute Index The following table consists of the attributes that can be mapped on a User during provisioning. Attribute Given Name Surname Email Role Send Welcome Email Description The user s first name. The User s last name. The user s email address. The user s role in Dropbox. Valid options include: member_only, support_admin, team_admin or user_management_admin. Whether to send a newly created user a welcome email. Valid options include true or false. Please note: If set to false, no email invitation will be sent to the user. Wipe Data on Delete Whether to delete data on user devices when they are suspended (deleted/disabled). Valid options include true or false. PingFederate Dropbox Connector 13 User Guide
Please note: If not specified, Dropbox will assume it should delete data on user devices. External Id A unique external identifier for the user. PingFederate Dropbox Connector 14 User Guide