INTEGRATE SALESFORCE.COM SINGLE SIGN-ON WITH THIRD-PARTY SINGLE SIGN-ON USING SENTRY A GUIDE TO SUCCESSFUL USE CASE
Legal Marks No portion of this document may be reproduced or copied in any form, or by any means graphic, electronic, or mechanical, including photocopying, taping, recording, or information retrieval system without expressed permission from Forum Systems, Inc. FORUMOS Firmware, Forum Systems XMLSec WebAdmin, Forum Systems XML Security Appliance, Forum Sentry, Forum Presidio, Forum XWall, Forum Sentry Web Services Gateway, Forum Presidio OpenPGP Gateway, Forum FIA Gateway, Forum XWall Type-PCI, Forum XWall Web Services Firewall and Forum XRay are trademarks and registered trademarks of Forum Systems, Inc. All other products are trademarks or registered trademarks of their respective companies. Copyright 2002-2012 Forum Systems, Inc. All Rights Reserved. Forum Systems Sentry Sample Use Case A D-ASF-SE-010029 2 w w w. f o r u m s y s. c o m
Contents INTRODUCTION... 4 Use Case Summary... 4 Sentry Technology Components Used... 4 Platforms... 4 USE CASE A... 5 Technical Summary... 5 Use Case Description... 5 Conclusion... 16 About Forum Systems... 17 3 w w w. f o r u m s y s. c o m
INTRODUCTION Use Case Summary Sentry provides single-sign-on to salesforce.com. Authentication to Sentry is provided through singlesign-on with a third-party identity provider. Sentry Technology Components Used This use case utilizes the following technology components that are available and integrated with the Forum Sentry product. Protocol Policies Mediation Policies Security Policies Task Policies Identity Policies Governance Policies HTTP Attribute Mapping RSA PKI, TLS Xpath Identification, Protocol Header Identification SAML SSO Flow Control, Size Control Platforms The use case can be implemented using any of the following available Forum Sentry form factors: FIPS 140-2 Hardware 4 w w w. f o r u m s y s. c o m
USE CASE A Technical Summary Sentry is a SAML identity provider that generates SAML tokens for single-sign-on with salesforce.com. Authentication to Sentry is performed through single-sign-on with a third-party identity provider. Sentry is a SAML service provider that consumes SAML tokens from the third-party identity provider. The thirdparty identity provider requires that Sentry provide a username, which is acquired from the user via an html form. Use Case Description 1) Login to salesforce.com. Under Company Profile -> My Domain, create the domain that will be used for single-sign-on. Allow time for the new domain to take effect and propagate to dns servers. 2) Under Sentry WebAdmin Resources -> PKI -> Keys, import or create a PKCS key pair to be used for SSL termination. This web site SSL certificate must be signed by a certificate authority recognized by client web browsers. 3) Under Sentry WebAdmin Resources -> Security Policies -> SSL, create a new SSL termination policy using the key pair created or imported for SSL termination in step #2. 4) Under Sentry WebAdmin Resources -> PKI -> Keys, import or create a PKCS key pair to be used for signing SAML assertions. If creating a new PKCS key pair, also download the certificate from Sentry for import to salesforce.com in step #6. 5) Under Sentry WebAdmin Resources -> Security Policies -> XML Signature, create a signature policy using the key pair created or imported for SAML signing in Sentry in step #4. 6) Login to salesforce.com. Under Security Controls -> Single Sign-On Settings, enable and configure single sign-on. a. Select the checkbox to enable SAML. b. Select SAML version 2.0. c. For SAML issuer, specify the Sentry default http://www.forumsys.com/sentry. (This can be any URI, but the URI must match the Sentry issuer configured in the Sentry STS policy.) d. Select Identity Provider Certificate, and load the X.509 certificate from the same key pair created or imported for SAML signing in Sentry in step #4. e. Specify the Sentry STS policy virtual URL as the Identity Provider Login URL, e.g. https://sentry.mycompany.com/salesforce. f. Specify the SAML User ID Type as salesforce.com username or Federation ID, depending on what type of salesforce.com user the Senty SAML assertion subject maps to. g. Specify Subject as the SAML User ID Location. ( Attribute can also be used but is not described here.) 5 w w w. f o r u m s y s. c o m
h. Specify the salesforce.com Entity Id, e.g. https://saml.salesforce.com. This URI must match the audience configured in the Sentry STS policy. 7) Under Sentry WebAdmin Gateway -> Gateway Policies -> Task List Groups, create a new empty task list group for single-sign-on, e.g. sso. 8) Under Sentry WebAdmin Gateway -> Gateway Policies -> Network Policies, create a new HTTP listener that uses HTTPS. Specify the SSL termination policy created in step #3. The listener protocol, host, and port must match the Identity Provider Login URL specified in the salesforce.com single sign-on settings, e.g. https://sentry.mycompany.com. 9) Under Sentry WebAdmin Gateway -> Gateway Policies -> STS Policies, create an STS policy for salesforce.com. a. SAML 2.0 is enabled by default. b. Expand SAML 2.0, and select confirmation method Bearer. c. Leave the default for the SAML issuer : http://www.forumsys.com/sentry. (This can be any URI, but the URI must match the SAML issuer configured in the salesforce.com single sign-on settings.) d. Specify the audience to match the Entity Id in the salesforce.com single sign-on settings, e.g. https://saml.salesforce.com. e. Select identification format Custom. (Other options can also be used but are not described here.) f. Select the appropriate value type where the salesforce.com username can be found, e.g. Username if the identified subject of the third-party single sign-on assertion 6 w w w. f o r u m s y s. c o m
corresponds to the username for salesforce.com. (For testing, the value type Constant can be used to specify a hard-coded salesforce.com username.) g. Uncheck the Include Certificates checkbox. (optional) h. Check the Target URI checkbox, and specify the login URL from the salesforce.com single sign-on settings, e.g. https://login.salesforce.com. i. Select the signature policy created in step #5. j. Uncheck the Sign key info checkbox. k. Set the Encoded Request Task List Group to the task list group created in step #7, e.g. sso. l. Click Next and select the HTTPS listener policy created in step #8. Specify the virtual directory for the STS policy. The virtual directory must match the Identity Provider Login URL specified in the salesforce.com single sign-on settings, e.g. /salesforce. m. Click Finish to create the STS policy. 7 w w w. f o r u m s y s. c o m
8 w w w. f o r u m s y s. c o m
10) Under Sentry WebAdmin Gateway -> Gateway Policies -> Documents, create a new html document, e.g. username.html to prompt for a username. The document must be valid XML and must contain SAMLRequest and RelayState hidden form parameters. For example: <html><body><br></br><br></br><div align="center"><h1> <form action="http://localhost:8020/salesforce" method="post"> Username: <input type="text" name="username"></input> <input type="hidden" name="samlrequest" value=""></input> <input type="hidden" name="relaystate" value=""></input> <input type="submit"></input> </form></h1></div></body></html> 9 w w w. f o r u m s y s. c o m
11) Under Sentry WebAdmin Gateway -> Gateway Policies -> Task Lists, create a new task list to prompt for a username, e.g. prompt for username. a. Add an Identify Document task with two Header Filters: Query Parameter SAMLRequest exists Query Parameter username not-exists 10 w w w. f o r u m s y s. c o m
b. Add a Replace Document task that references the html form created in step #10. 11 w w w. f o r u m s y s. c o m
c. Add a Map Attributes and Headers task that maps: Constant text/html -> Response Header Content-Type 12 w w w. f o r u m s y s. c o m
d. Add a Map Attributes to XML task that maps: Query Parameter SAMLRequest -> /html/body/div/h1/form/input[2]/@value Query Parameter RelayState -> /html/body/div/h1/form/input[3]/@value 13 w w w. f o r u m s y s. c o m
e. Add a Remote Routing task with the action Do not send to remote server. 12) Under Sentry WebAdmin Resources -> PKI -> Keys, import the X.509 certificate to be used for verifying SAML assertions from the third-party identity provider. 13) Under Sentry WebAdmin Resources -> Security Policies -> XML Verification, create a verification policy. Select Use a trusted pre-stored peer certificate, and select the certificate imported for SAML verification in step #12. (Alternately, a signer group can be created and used to verify signing certicates embedded in the SAML.) 14 w w w. f o r u m s y s. c o m
14) Under Sentry WebAdmin Gateway -> Gateway Policies -> Task Lists, create a new task list to authenticate the user via a third-party identity provider, e.g. authenticate. a. Add a Map Attributes and Headers task that maps: Query Parameter username -> User Attribute username b. Add an Identify User & Access Control task: Under access control, uncheck the Map identified user to a known user checkbox. Under identity mechanism, select Validate SAML SSO assertion & establish identity. Specify the appropriate third-party identity provider URL, e.g. https://idp.mycompany.com/login. Leave the default for the redirect parameter. (unused for this use case) Leave the default for the request issuer: http://www.forumsys.com/sentry. (This can be any URI, but the URI must match the settings in the third-party identity provider.) Select the Force authentication checkbox. Select the Request subject checkbox, and specify the Attribute name as username. Validate issuer is selected by default. Under issuer(s), specify the third-party SAML issuer URI, e.g. http://idp.mycompany.com. 15 w w w. f o r u m s y s. c o m
Select the Validate audience checkbox and specify http://www.forumsys.com/sentry as the audience, the same value used for the request issuer. (This can be any URI, but the URI must match the settings in the third-party identity provider.) Require signature is checked by default. Select the verification policy created in step #13. Under SAML identity mechanism, select Custom and Value Type Username. 15) Add the two task lists created in steps #11 and #14 to the task list group created in step #7. The prompt for username task list must precede the authenticate task list. 16) Navigate a web browser to the new salesforce.com domain created in step #1. The browser is redirected to Sentry, then the back-end identity provider, and ultimately back to salesforce.com. After successful Sentry authentication, the user is automatically logged in to salesforce.com. Conclusion Sentry integrates identity and access control across multiple authentication systems using saml singlesign-on. 16 w w w. f o r u m s y s. c o m
About Forum Systems Forum Systems, a wholly owned subsidiary of Crosscheck Networks, Inc., is a leader in Service Oriented Architecture (SOA) and secure service mediation. Through comprehensive Threat mitigation and Trust enablement, Forum s family of hardware, software, and cloud-based instances provides enterprises and government organizations with the foundation for achieving secure service mediation. Processing more than one billion transactions per day worldwide, the FIPS- and DoD-certified Forum products offer the industry s most comprehensive protection against XML- and SOAP-based vulnerabilities. Forum Sentry has been issued an industry-first patent (7,516,333) for XML security functions such as XML Encryption, XML Decryption, and XML Signatures using a network appliance. For more information, please visit www.forumsys.com. 17 w w w. f o r u m s y s. c o m