Box Connector Version 2.0 User Guide
2016 Ping Identity Corporation. All rights reserved. PingFederate Box Connector User Guide Version 2.0 March, 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: March 23, 2016. PingFederate Box Connector 2 User Guide
Contents Introduction... 4 Supported Features... 4 System Requirements... 4 ZIP Manifest... 4 Installation and Setup... 4 Getting Started... 4 Obtain Your OAuth 2.0 Access Token... 5 Downloading Box SAML 2.0 Metadata... 6 Synchronizing Existing Box Users and Groups... 6 Upgrading Existing Box Connectors... 7 Installing the Connector... 8 Configuring Server Settings... 8 Configuring a Connection... 8 Complete Setup of SAML SSO to Box... 13 Updating Box OAuth Tokens... 13 Provisioning Groups to Box... 13 Mapping Users to Groups... 14 Attribute Index... 14 Troubleshooting... 15 PingFederate Box 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 Box Connector requires installation of PingFederate 7.2.1 or higher. The Box Connector may require the following endpoints to be whitelisted on the firewall to allow outbound connections: https://account.box.com https://api.box.com ZIP Manifest The distribution ZIP file for the Connector contains the following: ReadMeFirst.pdf contains links to this online documentation. /legal: Legal.pdf copyright and license information. /dist contains libraries needed for the Connector: pf-box-quickconnection-2.0.jar PingFederate Box 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 Box Connector 4 User Guide
Obtain Your OAuth 2.0 Access Token The Box Connectors Outbound Provisioning functionality is built using Box 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 Box. To Obtain Your App Key & Secret from Box: 1. Log into Box as an administrative user. 2. Go to My Applications for Box (https://<account_subdomain>.app.box.com/developers/services/edit/). 3. Click the Create a Box Application link. Give your application a name, such as PingFederate Provisioning. Select your desired Scopes as the type of access you need. 4. Copy the client_id and client_secret values to use in the next section. 5. Add the following URL to the Redirect URI field: https://oauth.pingone.com/ocs/ppm/rest/v1/oauth/oastempcredresponse/ 6. Click the Save Application button to save your changes. To Generate Your OAuth 2.0 Access Token: 1. Go to the Ping OAuth Configuration Service here. 2. Select Box Connector from the drop down menu. 3. Enter the client_id you obtained above into the ClientID field. 4. Enter the client_secret you obtained above into the Client Secret field and click the Connect button. 5. Log in to Box as an administrative user. Note: If you are already signed in to Box, 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 Grant access to Box button to generate your Access and Refresh Tokens. PingFederate Box Connector 5 User Guide
7. You should have been redirected back to the OAuth Configuration Service and presented with an Access Token and Refresh Token. 8. Copy the Access Token to use when configuring the Box Connector. 9. Copy the Refresh Token to use when configuring the Box Connector. Downloading Box SAML 2.0 Metadata This Connector s quick-connection template uses a metadata XML file from Box to assist in configuring many settings in the SP Connection such as SSO endpoints and box certificates that are required. When asked during the Connection configuration steps, import the saml-metadata.xml that you have downloaded from Box. 1. Access the following URL to download the SAML 2.0 Metadata for Box: https://cloud.app.box.com/shared/3isa8qvvqn 2. Save the XML file to a desired location. Synchronizing Existing Box Users and Groups Important: If your Box 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 Box: Ensure that the value mapped to the Login attribute, (when configuring the connector) matches the existing Box Users Login exactly as it appears in Box. PingFederate Box Connector 6 User Guide
For example, if on the Attribute Mapping screen, the User Login attribute is mapped to the User mail attribute in your LDAP, this will synchronize a User that already exists on Box with a Login of jsmith@domain.com to the User in your LDAP who has a mail attribute value of jsmith@domain.com. When the Box connector provisions for the first time, this address will be used to synchronize the User in your LDAP data store with the User in Box. To provision existing Groups on Box: LDAP Groups will be synched with existing Groups on Box 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 Box, 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 Box. Likewise, any users that are members of the Accounting group in Box but are not members of the Accounting group in LDAP will be removed from that group in Box. Upgrading Existing Box Connectors 1. Before stopping the PingFederate server to upgrade the Box 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 Box Connector is configured. 3. Delete the existing Box Connector SP Connection and save. 4. Stop the PingFederate server if it is running. 5. Unzip the Box Connector distribution ZIP file into a holding directory. 6. Remove any versions of pf-box-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-box-oauth-helper.war json-x.jar BoxJavaLibraryVx.jar jackson-annotations-x.jar jackson-core-x.jar jackson-databind-x.jar 8. Delete the boxoauthtoken.conf located at <pf_install>/server/default/data/adapter-config 9. From the dist directory of the new version of the connector, copy the files: PingFederate Box Connector 7 User Guide
pf-box-quickconnection-2.0.jar into the directory: <pf_install>/pingfederate/server/default/deploy Important: Make sure to remove existing versions of Box Connector files. 10. Start the PingFederate server. 11. Create a new SP Connection, using Box as the Connection Template. 12. Follow the instructions in the Configuring a Connection section below in order to configure Metadata, and OAuth. 13. Access the Attribute Mapping for existing channel configurations and click Refresh Fields. 14. Ensure all new required fields (if any), are mapped appropriately or have a default value. 15. Once completed with the attribute configuration, click Done, Done, and Save. 16. Activate the SP Connection to resume Outbound Provisioning. Installing the Connector To install the Box 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 Box 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 Box 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 Box 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 Box 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. PingFederate Box Connector 9 User Guide
(SSO Configuration) On the SAML Profiles screen, ensure that the IdP-Initiated SSO and SP- Initiated SSO profiles are selected and click Next. (SSO Configuration) On the Signature Policy screen, ensure that the Always sign the SAML Assertion is selected and click Next. (SSO Configuration) Under the Credentials section do the following: On the Back-Channel Authentication screen click Configure. On the Inbound Authentication Type screen, select Digital Signature (Browser SSO profile only) and click Done. On the Back-Channel Authentication screen, click Next and on the Digital Signature Settings screen, select a Signing Certificate. On the Signing Verification Settings screen, click Manage Signature Verification Settings and on the Trust Model screen, ensure Unanchored is selected and click Next. PingFederate Box Connector 10 User Guide
On the Signature Verification Certificate screen, select the Box certificate as the Primary certificate and click Next. On the Target screen when configuring provisioning, fill in the following fields: Field Name Client Id Client Secret OAuth Access Token OAuth Refresh Token Group Provenance (Optional) Remove User Action User Create Enabled Value The Client Id for the application created in Box. For more information on obtaining a client Id and secret, see Obtain Your OAuth 2.0 Access Token. The Client Secret generated during application creation for Box. The OAuth Access Token generated by the OAuth Configuration Service. For more information on obtaining authorized OAuth tokens, see Obtain Your OAuth 2.0 Access Token. The OAuth Refresh Token generated by the OAuth Configuration Service. Optional and for Group Provisioning Only. This allows you to keep track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). This field should be a human-readable identifier up to 255 characters long. Setting this will also prevent Box users from editing this group directly through Box. This is desirable for oneway syncing of groups. Suspend (default) - When selected, if you delete a user from Active Directory, the user will be suspended in Box (also known as a Soft-Delete). Delete - When selected, if you delete a user from Active Directory, the user will be deleted in Box (also known as a Hard-Delete). True (default) Enables the ability to create users in PingFederate Box Connector 11 User Guide
User Update Enabled Box via PingFederate. False - When disabled, the ability to create users in box will be disabled. True (default) Enables the ability to update users in Box via PingFederate. False - When disabled, the ability to update users in box will be disabled. Note: Once PingFederate is restarted, these and subsequent authorized OAuth tokens are stored in boxoauthtoken.conf located at <pf_install>/server/default/data/adapterconfig. If these values in your SP Connection require updating at any time in the future, you will need to delete boxoauthtoken.conf prior to updating the values and restart PingFederate to regenerate this file with the new credentials. PingFederate Box Connector 12 User Guide
Complete Setup of SAML SSO to Box In order to setup your Box account for SSO you will need to do the following. 1. Once your Box Connection is configured, the metadata needs to be exported and used to configure your Box account for SSO. Download your metdata file which will include the following: Entity ID and Connection ID Redirect URL Public Certificate For more information, see Exporting Metadata in the System Administration chapter of the PingFederate Administrator s Manual (or click Help). 2. Navigate to the Box SSO Questionnaire https://community.box.com/t5/custom/page/page-id/submit_sso_questionaire and to upload your metadata. 3. Click Submit. Note: See this Box help article for more information on how to setup SSO for Box. Updating Box OAuth Tokens Use the following procedure to manually update the Box OAuth Tokens. 1. Obtain new Box OAuth tokens, see Obtain Your OAuth 2.0 Access Token 2. Delete the boxoauthtoken.conf located at <pf_install>/server/default/data/adapter-config 3. On the Target screen of the SP connection, update the following fields with the new OAuth Token values: OAUTH_ACCESS_TOKEN OAUTH_REFRESH_TOKEN 4. Restart PingFederate to regenerate this file. Provisioning Groups to Box The Connector enables an organization to provision and manage groups in Box. Tip: For instructions on synching the connector with existing Box groups, please refer to Synchronizing Existing Box 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 Box with the name of the group from LDAP. PingFederate Box Connector 13 User Guide
Updating Groups Renaming the group in LDAP will update the group s name in Box. Deleting Groups The Box Connector supports the ability to delete groups from Box. Deleting a group in LDAP will harddelete the group in Box on the next provisioning cycle. Warning: Deleting groups will permanently delete that group in Box. This operation cannot be undone. Mapping Users to Groups The connector supports the ability to manage user s group memberships in Box. 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 Box. 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 Box. Attribute Index The following table consists of the attributes that can be mapped on a User during provisioning. Attribute Name Login Language Description The user s full name (i.e., John Doe). The user s login, which is used for logging the user in. Please note: This value must be in the format of an email. This attribute cannot be updated by the Box provisioner. The user s language. Valid options include: ISO 639-1 Language Code. PingFederate Box Connector 14 User Guide
Timezone Space Amount Inactive Status Default The user s timezone. Valid options include: tz Database timezones. The user s total available space amount in bytes. A value of -1 grants unlimited storage. The user s default inactive status. The three inactive defaults include: inactive, cannot_delete_edit, or cannot_delete_edit_upload. Please note: When a user is suspended, the user status will be the value you have specified here. If no value, the default is inactive. Deleting the user in LDAP will always default to inactive regardless of this attributes value or the target page settings for removing a user (i.e., suspend vs. delete). Job Title Phone Address Role Can See Managed Users Is Sync Enabled Is Exempt from Device Limits Is Exempt from Login Verification Is External Collab Restricted The user s job title. The user s phone number. The user s address. The user s enterprise role. Valid options include: coadmin or user Whether the user can see other enterprise users in their contact list. Valid options include true or false. Whether or not the user can use Box Sync. Valid options include true or false. Whether to exempt the user from Enterprise device limits. Valid options include true or false. Whether or not this user must use two-factor authentication. Valid options include true or false. Whether this user is allowed to collaborate with users outside her enterprise. Valid options include true or false. Troubleshooting The following table lists potential problems administrators might encounter during the setup or deployment of the Box Connector, along with possible solutions: Problem Possible Solution PingFederate Box Connector 15 User Guide
Problem The exception "{"error":"invalid_grant","error_description":"re fresh token has expired"}" appears in server.log. Possible Solution The error indicates that refresh token has expired. A refresh token from Box has a lifespan of 60 days. Additionally, if a new refresh token has been requested, the old one will become expired. (see Updating Box OAuth Tokens to configure PingFederate with a new refresh token). PingFederate Box Connector 16 User Guide