SSO Plugin Case study: Integrating with Ping Federate J System Solutions Version 4.0
JSS SSO Plugin v4.0 Release notes Introduction... 3 Ping Federate Service Provider configuration... 4 Assertion Consumer Service URLs... 6 Signature Verification Certificate... 7 Importing the key into Ping Federate... 7 Digital Signature Settings... 8 Importing the certificate into a keystore... 8 Configuring SSO Plugin... 10 Testing the integration... 11
Page 3 of 12 Introduction This study provides in-depth steps for integrating the JSS SSO Plugin with Ping Federate. It does not aim to discuss: Ping Federate configuration in great detail as this should be known to the Ping Federate administrator, and there are plenty of tutorials online. SSL configuration of the Java web server running SSO Plugin, and there are plenty of tutorials online. Whilst SSL is not required for a PF integration, it is recommended for production deployments. The integration will: involve both message signing and verification within SSO Plugin and Ping Federate, providing security in both directions. The Ping Federate instance is SSL enabled, as it is out of the box, and the SSO Plugin instance is not. use the SAML POST profile, which is the most common solution for SAML integrations, because SAML Redirect can be unreliable, and SAML Artifacts are very complicated. use the default out of the box PF IDP configuration and login page.
Page 4 of 12 Ping Federate Service Provider configuration The Ping Federate administrator has created a Service Provider within PF for SSO Plugin. The PF SP configuration is summarised in the following screenshots.
Page 5 of 12
Page 6 of 12 The points of interest are as follows: 1. The Assertion Consumer Service URL (image 3). 2. The Single Logout (SLO) Service URL (image 3). 3. The Digital Signature Settings and Signature Verification Certificate (image 4). If SAML Artifacts are required, the SSO Plugin resolver URL can be noted under Artifact Resolver Locations (image 3). SAML Artifacts are not covered in this study. Assertion Consumer Service URLs These are defined as the endpoints to which a user can authenticate (on SSO Plugin) and the Test SSO URL has been configured. The URL is pointing to an SSO Plugin deployed to a Tomcat instance running on localhost (port 8080). There are two ways you can approach this configuration. 1. Define each end point a user could access, ie on BMC Mid Tier, http://host:port/arsys/home, http://host:port/arsys/forms (etc). 2. Define a universal access point within SSO Plugin that means only one Assertion Consumer Service URL is defined in PF. To do this, define a URL ending in /jss-sso/saml/authenticate ie on BMC Mid Tier, the URL would be http://host:port/arsys/jss-sso/saml/authenticate.
Page 7 of 12 Organisations will have different policies and ways of achieving this goal. The easiest way is to use the universal access point however this requires an additional configuration step within SSO Plugin: ticking the "Use single Assertion Consumer URL" checkbox when setting up the SAML configuration. For the purposes of this study, the first approach is demonstrated, ie defining specific URLs. Signature Verification Certificate For SSO Plugin to sign SAML requests that are verified by PF, public and private keys need to be generated. Using the keytool program, found in the Java Runtime Environment bin directory, run the following at the command line, which creates a new keystore (a collection of keys/certificates, each keyed with an 'alias') and populates it with a private key using an alias called sp: keytool -genkeypair -keyalg rsa -sigalg SHA256withRSA -keysize 2048 -keystore samltestkeystore.jks -alias sp This is enough for SSO Plugin to sign requests, but PF requires the public key to verify the requests. The following exports the public key: keytool -keystore samltestkeystore.jks -storepass password -exportcert - alias sp -file ~/tmp/ssoplugin.cer Importing the key into Ping Federate At the end of the Service Provider overview within PF, look for and select Signature Verification Certificate. This will allow you to select a certificate. Click manage certificates, and then import. Browse for the public key exported from the keystore (ie ssoplugin.cer) and import as per the screenshot.
Page 8 of 12 Then return to the Service Provider overview, select Signature Verification Certificate and select the SSO Plugin key that has been imported. Digital Signature Settings This defines the certificates used to sign the SAML responses sent from PF to SSO Plugin. For SSO Plugin to verify the SAML sent by PF, the certificate needs to be exported from PF and stored in a file. To do this, click Digital Signatures, Manage Certificates, Export on the certificate selected for the SP, and export the 'certificate only'. We assume this is stored in a file called ping.crt. Importing the certificate into a keystore For SSO Plugin to use the certificate exported from Ping, we must import it into the keystore created earlier. To do this, run the keytool command, importing the certificate using an alias called ping: keytool -keystore samltestkeystore.jks -storepass password -import -alias ping -file ping.crt Owner: CN=localhost, O=Quick Start App, C=US Issuer: CN=localhost, O=Quick Start App, C=US Serial number: 130db8cd483
Page 9 of 12 Valid from: Wed Jun 29 14:18:17 BST 2011 until: Fri Jun 05 14:18:17 BST 2111 Certificate fingerprints: MD5: 8D:4E:8C:8F:69:46:E4:83:82:09:C2:E4:6E:4A:85:2A SHA1: 69:7D:39:A0:BF:D5:90:BF:79:11:5E:F3:1C:55:EA:F6:5F:39:F4:E5 SHA256: D5:DF:DE:E9:BF:D9:C1:81:87:57:DC:7C:14:34:81:5D:22:B2:01:F5:FC:F6:49:24:7C: A7:AE:16:80:9C:77:62 Signature algorithm name: SHA1withRSA Version: 3 Trust this certificate? [no]: yes Certificate was added to keystore
Page 10 of 12 Configuring SSO Plugin The following image shows the SSO Plugin configuration for the PF integration. It assumes that the universal URL has not been configured in the Assertion Consumer URLs within the SP configuration, and hence the "Use single Assertion Consumer URL" checkbox is not selected. The keystore (samltestkeystore.jks) has been placed on the application classpath, ie in the tomcat/webapps/authentication-service/web-inf/classes directory.
Page 11 of 12 Testing the integration Once SSO Plugin has been configured and no errors are reported when the 'Set configuration' button is pressed, the Test SSO link will create a SAML request, sign it using the private key configured when the keystore was created, and the browser will send the message to PF. If PF is configured incorrectly, it does not always report the errors in a meaningful fashion to the browser. Typically, it sends the browser back to the requested page (ie the Test SSO page) and hence SSO Plugin creates a new request which gets sent to PF. If this loop occurs three times, SSO Plugin displays an error page to avoid a continuous loop. PF will have written error messages to the PF logs and these should be examined. If PF is configured correctly, and in our case we're using the default PF IDP, it will display a login page: When the user logs in (ie the password for user john is test), PF will create a SAML response, sign it with its private key and sent the message back to SSO Plugin. SSO Plugin will verify the message using the key exported from PF and imported into the keystore, before displaying the username in the Test SSO page:
Page 12 of 12 This completes the integration. The next steps are to implement SSL on the Java web server running SSO Plugin and to implement either a universal URL for the Assertion Consumer URL or to specify all the URLs in the target application (ie BMC Mid Tier, HP Web Tier, etc) that a user can access through PF. If you have any questions or require assistance, please contact the JSS support team.