Quick Connection Guide

Transcription

1 ServiceNow Connector Version 1.0 Quick Connection Guide

2 2015 Ping Identity Corporation. All rights reserved. PingFederate ServiceNow Connector Quick Connection Guide Version 1.0 August, 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: August 14, PingFederate ServiceNow Connector 2 ServiceNow Quick Connection Guide

3 Contents Introduction... 4 Supported Features... 4 System Requirements... 4 ZIP Manifest... 4 Installation and Setup... 4 Getting Started... 4 Installing the Connector... 7 Upgrading the Connector... 7 Configuring Server Settings... 7 Configuring a Connection... 8 Attribute Index Troubleshooting PingFederate ServiceNow Connector 3 User Guide

4 Introduction This document assumes you have read the Introduction section of the SaaS Connector User Guide. Supported Features User Outbound Provisioning IdP- and SP-initiated SSO System Requirements The ServiceNow Connector requires installation of PingFederate or higher. 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-servicenow-quickconnection jar PingFederate ServiceNow Connector Ping Identity Master Update Set.Patch 6.xml The update set required to be installed in ServiceNow for provisioning. 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. Obtain Your ServiceNow Instance This Connector requires the subdomain to access your ServiceNow instance for SSO and Outbound Provisioning. PingFederate ServiceNow Connector 4 ServiceNow Quick Connection Guide

5 Example: YourSubDomain.servicenow.com Update your ServiceNow Instance Included in the dist/ folder of the Connector is a Ping Identity Master Update Set.Patch 6.xml file that is required to be imported and committed to your ServiceNow instance. Please refer to ServiceNow Update Set documentation for how to install the update set properly. Obtain Your ServiceNow Integration User Credentials The update set that must be imported and installed into your ServiceNow instance includes a user role, u_ping_identity_import_table_user, with Administrator privileges in order to perform provisioning and role-syncing requests. Log in to your ServiceNow instance as your Administrator account and perform the following steps to create an integration user: 1. Under the Organization Management header in the Navigator sidebar, click Users. 2. Select New at the top of the screen. 3. Enter u_ping_identity_import_table_user for the User ID and create a secure password for the user. Select the Web service access only and Internal integration user checkboxes. Click Submit. 4. Under the User Administration header in the Navigator sidebar, click User Roles. 5. Select New at the top of the screen. 6. Use the search assist or enter the User ID of the user you created in step 3 in the User field. 7. Use the search assist or enter u_ping_identity_user_import_table_user in the Role field. 8. Click Submit. The user created in the steps above will be used later when configuring provisioning in the connector. Important: It is imperative that the provided integration user is used for setting up the connector. Logging facilities in ServiceNow will not function properly if a different account is used. Obtain Your ServiceNow 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. Before configuring your SP Connection, you must first download your metadata file that can be retrieved from your ServiceNow instance. To Prepare servicenow-saml-metadata.xml: 1. Request the SAML 2.0 Single Sign-On - Update 1 Plugin for your ServiceNow instance. 2. After the plugin has been installed, login as the administrator account and navigate to the SAML 2 Single Sign On header in the sidebar. 3. Under the SAML 2 Single Sign On sidebar header, click the Properties tab. a. Under the Identity Provider Properties subheader: PingFederate ServiceNow Connector 5 User Guide

6 Set the Identity Provider URL to the SAML 2.0 Entity ID of your PingFederate server (PingFederate > Administrator Console > Server Settings > Federation Info). Set the base URL to the Identity Provider s AuthnRequest Service to your PingFederate server s SSO endpoint ( (optional) Enable the checkbox Sign AuthnRequest. Set the base URL to the Identity Provider s SingleLogoutRequest service to your PingFederate server s SLO endpoint ( Enable the checkbox Sign LogoutRequest.Set the base URL where the initial SAML 2.0 AuthnRequest is sent using the SAMLRequest parameter to your PingFederate server s SSO endpoint ( b. Under the Service Provider (Service-Now) properties: Make sure the Service-Now instance homepage, issuer and audience URI all point at your instance of Service-Now. Change the User table field to match with the SAML Subject s NameID element to user_name. Set the NameID Policy to use for returning the Subject s NameID in the SAMLResponse to urn:oasis:names:tc:saml:1.1:nameid-format:unspecified. c. Finally, navigate back to the top of the page and select Enable external authentication. 4. Under the SAML 2 Single Sign On header, click Certificate and upload your desired Digital Signing certificate (PingFederate > Administrator Console > Digital Signing & XML Decryption Keys & Certificates) from your PingFederate server. Use SAML 2.0 for the name of the certificate in Service Now. SLO Certificate: Make sure the certificate found in the SAML 2.0 SP Keystore, a Java Key Store has been extracted and then uploaded into PingFederate (PingFederate > Administrator Console > Trusted CAs) to configure Single Log-out. 5. Under the SAML 2 Single Sign On header, click the Metadata tab and copy the resulting metadata into a file and save it as an XML file. Synchronizing Existing ServiceNow Users Important: If your ServiceNow instance already has users you wish to provision with the ServiceNow connector, this is possible by following the steps below. To provision existing User accounts on ServiceNow Ensure that the value mapped to the username attribute, when configuring the attribute mapping, matches the attribute containing the user s username in AD. These usernames must exactly match to be synchronized in ServiceNow, else a duplicate record will exist for the user if they already have a preexisting account. For example, on the Attribute Mapping screen, the user s username attribute on ServiceNow is mapped to the user s SamAccountName attribute in your LDAP. This will synchronize a user that already exists PingFederate ServiceNow Connector 6 ServiceNow Quick Connection Guide

7 on ServiceNow with a username of test.user. In this case, the user s SAMAccountName attribute in LDAP would also have to be test.user. Installing the Connector Important: If you are upgrading to a newer version of the ServiceNow Connector please follow the steps in the Upgrading the Connector section of this User Guide. Important: This section directs you to the SaaS Connector User Guide for most of the steps to install this Connector but contains additional steps that need to be followed to successfully install this Connector. Ensure you follow the additional steps below as directed. To install the ServiceNow Connector, please follow the instructions in the Installing the Connector section of the SaaS Connector User Guide, making the adjustments listed in the following section. Adjustments to make: Skip step 4 in the Installing the Connector section of the SaaS Connector User Guide. Upgrading the Connector 1. Stop the PingFederate server if it is running. 2. Unzip the new ServiceNow Connector distribution ZIP file into a holding directory. 3. Remove any old versions of pf-servicenow-quickconnection-x.x.x.jar from: <pf_install>/pingfederate/server/default/deploy 4. If you are upgrading from version 1.0 of the ServiceNow Connector, you must also remove the following files from the same directory: prov-cpl jar gson jar 5. From the dist directory of the new version of the connector, copy pf-servicenowquickconnection jar into the directory: <pf_install>/pingfederate/server/default/deploy 6. Restart the PingFederate server. Configuring Server Settings To configure Server Settings in preparation of configuring the ServiceNow Connector, please follow the instructions in the Configuring Server Settings section of the SaaS Connector Guide. PingFederate ServiceNow Connector 7 User Guide

8 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 ServiceNow 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 ServiceNow as the Connection Template to use for this SP Connection. You will be asked to provide the Metadata File you generated 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 ServiceNow Connector 8 ServiceNow Quick Connection Guide

9 On the Allowable SAML Bindings screen, ensure that both POST and Redirect SAML bindings are enabled and click Next. (SLO Configuration) If you have enabled SLO, On the SLO Service URLs screen, add two endpoint URLs for the bindings you intend to use and click Next. PingFederate ServiceNow Connector 9 User Guide

10 (Optional) On the Digital Signature Settings screen, once you select your Signing Certificate, enable the checkbox to include the certificate in the signature <KeyInfo> element and click Next. (SLO Configuration) If you have enabled SLO, an additional tab called Signature Verification Settings will be available, select the certificate used to verify the digital signatures and click Next. This certificate should match the one contained in the SAML 2.0 SP Keystore on your ServiceNow instance. On the Target screen when configuring provisioning, enter the integration user s username and password in the Administrator_Username and Administrator_Password fields that you created in an earlier step. Enter your instance name as the ServiceNow_Subdomain you obtained in the Getting Started section of this User Guide and click Done. PingFederate ServiceNow Connector 10 ServiceNow Quick Connection Guide

11 Configuring SSO When configuring SSO for the ServiceNow Connector, the metadata provided by ServiceNow neglects to include the HTTP-Redirect SAML binding. This shortcoming is easily mitigated by using PingFederate s UI to select Redirect in the Allowable SAML Bindings page of the Browser SSO setup. PingFederate ServiceNow Connector 11 User Guide

12 Attribute Index The following table consists of the attributes that can be mapped on a User during provisioning. Attribute Description Active This attribute is statically mapped to the activation of the user in Active Directory. This attribute is used when the user is deleted or disabled in Active Directory Business phone The phone number to contact the user at work. City The city where the user resides. Country code The country code that represents the country where the user lives. This attribute has a default value in ServiceNow and Country codes might have to be updated in ServiceNow to account for other allowable values for this field. The address for the user. Employee number An alternative value to identify the user. First name The user s first name. Home phone Language Last name The user s home phone number. The user s primary language. ServiceNow restricts the allowable values in this field, but the list of acceptable values can be updated. The user s last name. Middle name The user s middle name. Mobile phone The user s mobile phone number. Password The user s password. NOTE: this attribute will be sent in plain text to ServiceNow and stored in the import table in plain text. Configuring SSO & not including an attribute mapping to this field is recommended. PingFederate ServiceNow Connector 12 ServiceNow Quick Connection Guide

13 Photo A URL to the user s profile picture in ServiceNow. Role A multi value attribute representing all the roles they act as in ServiceNow. Only preexisting Roles in ServiceNow will be synchronized with values in this attribute. If a particular Role attribute cannot be found, no linkage occurs. State / Province The state or province the user resides in. Street The street address of the user. Time zone The time zone the user resides in. Title User ID The user s title (e.g. Mrs., Mr., etc). The user s username. This value will be used to synchronize preexisting users in ServiceNow. Zip / Postal code The postal/zip code of the user. Troubleshooting The following table lists potential problems administrators might encounter during the setup or deployment of the ServiceNow Connector, along with possible solutions: Problem (SSO Failure) The ServiceNow instance does not send an AuthnRequest (SAMLRequest) to PingFederate. Possible Solution 1. Ensure that the correct SSO plugin is installed on your ServiceNow instance.(saml 2.0 Update 1). 2. Ensure that your base URL to the Identity Provider s AuthnRequest service is correct (see Obtain Your ServiceNow SAML 2.0 Metadata XML ). 3. Contact ServiceNow as there may be an issue with your instance preventing it from sending the SAML message. PingFederate ServiceNow Connector 13 User Guide