Slack Connector. Version 2.0. User Guide

Transcription

1 Slack Connector Version 2.0 User Guide

2 2015 Ping Identity Corporation. All rights reserved. PingFederate Slack Connector User Guide Version 2.0 December, 2015 Ping Identity Corporation th Street, Suite 100 Denver, CO U.S.A. Phone: ( outside North America) Fax: Web Site: 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: December 10, PingFederate Slack Connector 2 User Guide

3 Contents Introduction... 4 Supported Features... 4 System Requirements... 4 ZIP Manifest... 4 Installation and Setup... 4 Getting Started... 4 Installing the Connector... 9 Configuring Server Settings... 9 Configuring a Connection Complete Setup of SAML SSO to Slack Provisioning Groups to Slack Mapping Users to Groups Attribute Index PingFederate Slack Connector 3 User Guide

4 Introduction This document assumes you have read the Introduction section of the SaaS Connector User Guide. Supported Features Outbound User Provisioning Outbound Group Provisioning Outbound User to Group mapping Browser-based SP and IdP-initiated SSO System Requirements The Slack Connector requires installation of PingFederate or higher. The Slack Plus accounts are required for SAML SSO integration. 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-slack-quickconnection-2.0.jar PingFederate Slack 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 Slack Connector 4 User Guide

5 Obtain Your OAuth 2.0 Access Token The Slack Connectors Outbound Provisioning functionality is built using Slack s SCIM API, which requires an OAuth 2.0 Access Token for authentication. To obtain your token you will first need to obtain a client_id and client_secret. To Obtain Your client_key & client_secret: 1. Log into Slack as an administrative user 2. Go to the Slack API Applications page 3. Click the Create a new application button and fill in the form as follows: PingFederate Slack Connector 5 User Guide

6 Enter any descriptive name into the Name field Select the appropriate Team to provision users into Enter any description or Provisions users to Slack into the Describe what your app does field Enter the following URL into the Redirect URI(s) field: PingFederate Slack Connector 6 User Guide

7 Click the Create Application button Copy the Client ID (client_id) and Client Secret (client_secret) values to use in the next section. To Obtain Your OAuth 2.0 Access Token: 1. Visit Ping Identity s OAuth Configuration Service (OCS) here. 2. Select the Slack Connector option from the select menu. 3. Enter your client_id in the ClientID text box. 4. Enter your client_secret in the Client Secret text box. 5. Click the Connect button. PingFederate Slack Connector 7 User Guide

8 6. Enter your team s Slack domain and click Sign In 7. Log into Slack with an administrative account. Note: If you are already signed in to Slack, you may not be asked to log in again. Please be sure that the account you are signed in under is an administrative account. 8. You will be informed that your Application is requesting permission to administer your Slack team. Click the Authorize button to continue. 9. You should have been redirected back to the OCS and presented with an Access Token. Make note of the Access Token to use in a later step when Cofiguring your connection. PingFederate Slack Connector 8 User Guide

9 Obtain the Slack 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 metadata.xml: 1. Open the saml-metadata.xml file contained with your connector with a text editor of your choice. 2. Replace the instances of TEAM_NAME with the team name for the Slack account: For example, if the URL you use to access your Slack team account is then your TEAM_NAME is myteamdomain. 3. Once you have updated the saml-metadata.xml file, save your changes. Synchronizing Existing Slack Users Important: If your Slack account already has Users you wish to provision with the Slack connector, this is possible by following the steps below. To provision existing User accounts on Slack: Ensure that the value mapped to the primary attribute, (when configuring the connector) matches the existing Slack Users primary exactly as it appears in Slack. For example, if on the Attribute Mapping screen, the User primary attribute is mapped to the User mail attribute in your LDAP. This will synchronize a User that already exists on Slack with a primary address of sample@example.com to the User in your LDAP who has a mail attribute value of sample@example.com. When the Slack connector provisions for the first time, this attribute will be used to synchronize the User in your LDAP data store with the User in Slack. Installing the Connector To install the Slack 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 Slack Connector, please follow the instructions in the Configuring Server Settings section of the SaaS Connector Guide. PingFederate Slack Connector 9 User Guide

10 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 Slack 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 Slack 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. 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 Slack Connector 10 User Guide

11 (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 Attribute Contract screen, ensure that the SAML_SUBJECT name format is set to urn:oasis:names:tc:saml:2.0:nameid-format:persistent. PingFederate Slack Connector 11 User Guide

12 Note: If needed, an administrator can customize name-format alternatives via the customname-formats.xml configuration file located in this directory: <pf_install>/pingfederate/server/default/data/config-store. In order to SSO with the Slack connector, add the following xml item under the saml2-subjectname-formats section: <con:item name="urn:oasis:names:tc:saml:2.0:nameidformat:persistent">urn:oasis:names:tc:saml:2.0:nameidformat:persistent</con:item> (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. 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. PingFederate Slack Connector 12 User Guide

13 Complete Setup of SAML SSO to Slack The following section describes the steps for configuring SP and IdP-initiated SSO to Slack. Note: This section requires two pieces of information that can be found within PingFederate. The first is the SAML 2.0 Entity ID, which can be found under on the Server Settings page and the second is the exported certificate used to sign the SAML assertion (configured in step 19 of Configure a Connection). 1. Navigate to and sign in with your Team Owner credentials. 2. Navigate to Authentication to view the SAML Authentication section. 3. Configure SAML authentication to view the SAML provider options. 4. Select Custom SAML 2.0 and click Configure. 5. Enter the PingFederate SAML endpoint into the SAML 2.0 Endpoint field Copy and paste the SAML 2.0 Entity ID and signing certificate into the Identity Provider Issuer and Public Certificate, respectively. Tip: In order to override SAML 2.0 Entity ID on the Server Settings page for your SP Connection, navigate to General Info screen to add a Virtual Server ID. This value will be sent as the SAML Issuer URL. PingFederate Slack Connector 13 User Guide

14 7. Click Save Configuration to complete Slack SSO Setup. This will initiate the SSO workflow and require the team owner to succesfully complete the SSO workflow before all changes are saved. Once saved, s will be sent to team members in order to have them set up SSO with their Slack accounts. Provisioning Groups to Slack The Connector enables an organization to provision and manage groups to Slack. Creating Groups To create a group, target a group in LDAP to be provisioned. The Slack Connector will create the group in Slack with the name of the group from LDAP. To provision existing Group accounts on Slack If your Slack has groups that you want the connector to manage, you will need to ensure that the LDAP group name matches the existing Slack group displayname exactly as it appears in Slack. When the Slack connector provisions for the first time, this displayname attribute will be used to synchronize the Group in your LDAP data store with the Group in Slack. Updating Groups PingFederate Slack Connector 14 User Guide

15 Renaming the group in LDAP will update the group name in Slack on the next provisioning cycle. Deleting Groups The Slack Connector supports the ability to delete groups from Slack. Deleting a group in LDAP will hard-delete the group in Slack on the next provisioning cycle. Mapping Users to Groups The Slack Connector supports the ability to manage user s group memberships. A user can be a member of one or more groups. 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. Attribute Index The following table consists of the attributes that can be mapped on a User during provisioning. Attribute username primary givenname familyname title profilephotourl Description The user s username in Slack. The user s address. The user s first name. The user s last name. The user s title. The URL to an online photo for the user. Must be a valid URL to an image file ending in.jpg,.gif or.png. PingFederate Slack Connector 15 User Guide