Ping Identity RSA SecurID Ready Implementation Guide Partner Information Last Modified: December 13, 2013 Product Information Partner Name Ping Identity Web Site www.pingidentity.com Product Name PingFederate Version & Platform 6.x and 7.0 Product Description PingFederate is the leading enterprise identity bridge for standards-based federated identity management. By integrating silos of identity and applications inside your enterprise, across partners and into the cloud, PingFederate enables federated single sign-on and identity management, secure mobile access, API security, social identity integrations and automated user provisioning. 1
Solution Summary Ping Identity PingFederate is a lightweight and powerful identity bridge that delivers a comprehensive identity management solution for federated access to resources that use existing identity infrastructures. PingFederate supports standard protocols like SAML, OAuth and OpenID Connect, to offer your users, customers and partners secure Single-Sign-On (SSO) access to any cloud or on-premise application. It provides powerful adaptive federation and authorization capabilities, enabling you to use the right level of security for the right user at the right time. Ping Identity offers customers a PingFederate Identity Provider (IdP) adapter that delegates SSO authentication requests to an RSA Authentication Manager server. The PingFederate RSA SecurID Adapter supports both RSA SecurID two-factor authentication and RSA Risk-Based Authentication (RBA). The adapter is part of the PingFederate RSA SecurID Integration Kit, which is available for customers to download at https://www.pingidentity.com. Important: If you have trouble locating or downloading the PingFederate RSA SecurID Integration Kit, contact Ping Identity Customer Support. When a user initiates an SSO request from a Service Provider (SP) application that has been protected by RSA SecurID/RBA, the IdP server calls the adapter to verify the user s credentials. When the adapter returns the authentication results, the IdP server takes the appropriate action. Upon a successful authentication, the server will generate a SAML identity assertion that grants the user SSO access to the application and other protected resources. Upon a failed authentication, the server will deny the user access to the SP application. RSA Authentication Manager supported features RSA SecurID Authentication via Native RSA SecurID Protocol RSA SecurID Authentication via RADIUS Protocol On-Demand Authentication via Native SecurID Protocol Risk-Based Authentication Risk-Based Authentication with Single Sign-On RSA Authentication Manager Replica Support RSA SecurID Software Token Automation RSA SecurID SD800 Token Automation RSA SecurID Protection of Administrative Interface Yes No Yes Yes Yes Yes No No No 2
RSA SecurID Authentication Process Diagram The following figure shows an SP-initiated SSO follow-of-events in which PingFederate authenticates a user to an SP application using the RSA SecurID Adapter: Note: This example depicts an SP-initiated request in which both the IdP and SP are using PingFederate. Although this is the optimal use case, PingFederate can be configured to accept any valid SAML authentication request. PingFederate also supports IdP-initiated SSO. The flow-of-events for this use case begins at step three. 1. The user initiates SSO from an SP application through the PingFederate SP server. 2. The PingFederate SP server sends a SAML AuthnRequest to the PingFederate IdP server. 3. The PingFederate IdP server invokes the adapter to prompt the user to submit RSA SecurID credentials for verification. 4. The adapter sends the user s authentication credentials to RSA Authentication Manager. 5. RSA Authentication Manager validates the credentials and returns the result. 6. If validation succeeds, the PingFederate IdP server generates a SAML assertion for the user and passes it to the PingFederate SP server. If validation fails, PingFederate denies the user access to the SP resource. 3
RSA Authentication Agent Configuration RSA Authentication Agents are custom or ready-made software applications that securely pass user authentication requests to and from RSA Authentication Manager. RSA provides the RSA Authentication Agent API for building custom agents, as well as a variety of out-of-the-box agents for protecting access to various operating systems and web resources. Note: PingFederate s custom agent is contained within the RSA SecurID Adapter. All agents must be registered with RSA Authentication Manager in order for the server to locate them and establish secure communication channels with them. Use the RSA Security Console to register an agent for every PingFederate server in your environment that uses the RSA SecurID Adapter. You need the following information to register a PingFederate agent: the hostname of the PingFederate server IP addresses for all of the PingFederate server s network interfaces Note: Hostnames must resolve to valid IP addresses on the local network. When you register an Authentication Agent, set its agent type to Standard Agent. Refer to the RSA Authentication Manager Administrator s Guide for more information about RSA Authentication Manager Authentication Agents. RSA SecurID Files RSA SecurID Authentication Agent Files Files Location sdconf.rec <pf_home> * /pingfederate/server/default/data/adapter-config/ securid <pf_home>/pingfederate/server/default/data/adapter-config/ sdstatus.12 <pf_home>/pingfederate/server/default/data/adapter-config/ sdopts.rec <pf_home>/pingfederate/server/default/data/adapter-config/ Note: The Appendix contains detailed instructions for managing these files. * <pf_home> represents PingFederate s base installation directory. 4
Partner Product Configuration Before You Begin This document contains instructions for enabling RSA SecurID two-factor authentication and Risk-Based Authentication for PingFederate users. You should have working knowledge of RSA Authentication Manager and PingFederate, as well as access to the appropriate administrative documentation. Ensure that that both products are running properly prior to configuring the integration. This document is not intended to suggest optimal installations or configurations. Important: You must download the RSA Auth Agent Java SDK v8.1.2 from RSA SecurCare Online to obtain a copy of the cryptoj.jar file. Contact RSA if you have any problems or questions. Configure the PingFederate RSA SecurID Adapter for RSA SecurID Follow these steps to install and configure the adapter : 1. Download the PingFederate RSA SecurID Integration Kit from Ping Identity s website and place it in a temporary directory. If you have trouble locating or downloading the kit, contact Ping Identity Customer Support. 2. Use the RSA Authentication Manager Server s Security Console to download the server s sdconf.rec file, and save the file to a temporary directory. 3. Before logging out of the Security Console, create a test user and assign an RSA SecurID token to the user. You will need the token to perform a test authentication. 4. Stop the PingFederate server if it is running. 5. Copy the pf-securid-adapter-1.0.jar and pf-securid-images.war files from the RSA SecurID integration kit s dist directory and paste them into the <PF-install>/server/default/deploy directory. 6. Copy the RSA SecurID API files, authapi.jar (included in the kit) and cryptoj.jar (available at RSA SecurCare Online), and paste them into the <PF-install>/server/default/lib directory. 7. Copy the remaining files from the dist directory and paste them into the <PF-install>/server/default/conf/template directory. 8. Start the PingFederate server, log in to the administrative console and click the Adapters link in the My IdP Configuration My Integration Settings section. PingFederate 6 PingFederate 7 (For more information about IdP Adapters, see the PingFederate Administrator s Manual.) 5
9. Click the Create New Instance button on the Manage IdP Adapter Instances page. 10. Choose a descriptive name for the adapter and enter it into the Instance Name field. 11. Choose a unique, alphanumeric string for PingFederate to use to identify the adapter and enter it into the Adapter Instance field. The string may not contain whitespaces. 12. Select SecurID Authentication Adapter from the Type dropdown list and click the Next button. PingFederate 6 PingFederate 7 6
13. Click the Browse button to the right of the SecurID Configuration File field, navigate to your temporary directory and select the sdconf.rec file. 14. Enter the RSA SecurID test user s username in the Test Username field. You will submit the user s username and tokencode to RSA Authentication Manager for verification. Important: You must have the test user s RSA SecurID token before you proceed. You will submit the user s credentials to RSA Authentication Manager for an initial authentication (See Step 16). Upon a successful authentication, the adapter will write a node secret to PingFederate s adapter-config folder. If the adapter has a problem saving the node secret, you must create a new one and import it manually. See the Appendix for details. 15. Click the Show Advanced Fields button and review the adapter s optional configuration settings. See the Appendix for details. 16. Enter the user s RSA SecurID tokencode into the Test Passcode field and click the Next button. PingFederate will submit the credentials to RSA Authentication Manager for verification. PingFederate 6 PingFederate 7 7
17. Click the Next button on the Adapters screen. 18. Select the Pseudonym checkbox on the Adapter Attributes screen and click the Next button. 19. Verify your configuration settings on the Summary screen and click the Done button. 20. Click the Save button on the Manage IdP Adapter Instances screen. Note: This completes the adapter s configuration process. You may now configure or modify your SP connection(s) to use the RSA SecurID Adapter instance. See the PingFederate Administrator s Manual for details. Configure the PingFederate RSA SecurID Adapter for RBA Before you can configure the adapter to use RSA Risk-Based Authentication, you must enable RSA SecurID as described in the previous section. To enable RBA, you must then download a custom JavaScript template, copy it to the RSA Authentication Manager server, generate a JavaScript file from the template and paste its contents into the PingFederate RSA SecurID login page s HTML template. Important: You must configure the adapter for RSA SecurID authentication before proceeding. 1. Download the Ping_Identity_PingFederate_6x.zip file from the following link and extract its contents into a temporary directory. This ZIP contains the PingFederate RBA integration s JavaScript template, Ping_Identity_PingFederate_6x.xml. https://sftp.rsa.com/human.aspx?username=partner&password=rsasecured&arg01=973088298&arg12=d ownloaddirect&transaction=signon&quiet=true Important: If the file doesn t download, copy the link and paste it into your browser s address field. 2. Stop the PingFederate server if it is running. 3. Connect to your RSA Authentication Manager server s virtual appliance using an SCP or SSH client and navigate to the /opt/rsa/am/utils/rba-agents directory. 4. Upload the Ping_Identity_PingFederate_6x.xml file from your temporary directory to the rba-agents directory above and disconnect your SCP/SSH client session. 5. Log in to the RSA Authentication Manager Security Console, open your PingFederate agent for editing, scroll to the Risk-based Authentication section and check the Enable this Agent for riskbased authentication checkbox. 6. Set the access restriction and authentication method options based on your requirements and click the Save agent & Go to Down Page button. 7. Select Ping Identity PingFederate 6.x from the Agent Type dropdown list, click the Download File button and save the file (am_integration.js) to a temporary directory. Note: RSA Authentication Manager will use the XML template you uploaded to generate a JavaScript file containing functions the adapter needs to communicate with the RSA RBA web application. 8
8. Navigate to the <PF-install>/dist/template directory, open the file named SecurIDAuthenticationAdapter.form.template.html and locate the closing head tag (</head>): 9. Copy the following HTML <script> tag and paste it before the closing head tag above. <script language="javascript"> 10. Paste the contents of the am_integration.js file after the <script> tag above and paste the closing </script> tag below directly after it. </script> 11. Locate the opening body tag: <body id="loginbody"> and replace it with the following body tag: <body id="loginbody" onload="javascript:redirecttoidp();"> 12. Start the PingFederate server. 9
RSA SecurID Login Screens Login Screen: User-defined New PIN Prompt: 10
System-generated New PIN Prompt: Next Tokencode Prompt: 11
RSA RBA Login Screens When you configure the PingFederate RSA SecurID adapter for RSA Risk-Based Authentication, you enable RSA SecurID authentication and modify the RSA SecurID login page to call a custom JavaScript function when it loads. The Javascript function collects information about the login page s form action, URL and variable names, and posts the data to RSA s standalone RBA web application. The application uses RBA to verify the user s identity. Upon successful authentication, the RBA application generates an RSA passcode for the user and posts the user s credentials back to the PingFederate login form. The standard PingFederate RSA SecurID integration authenticates the credentials behind the scenes, and grants the user access. The following images are screenshots of the RSA RBA application s logon prompts. RBA User ID Logon Prompt: RBA Password Logon Prompt: 12
RBA Challenge Question Logon Prompt: RBA Device-Binding Option Prompt: 13
Certification Checklist For RSA Authentication Manager 8.0 Date Tested: November 21, 2013 Certification Environment Product Name Version Operating System RSA Authentication Manager 8.0 Virtual Appliance RSA Authentication Agent API 8.1 Red Hat Linux 5 Ping Identity PingFederate 6.6 Red Hat Linux 5 Mandatory Functionality RSA Native Protocol RADIUS Protocol New PIN Mode Force Authentication After New PIN Force Authentication After New PIN N/A System Generated PIN System Generated PIN N/A User Defined (4-8 Alphanumeric) User Defined (4-8 Alphanumeric) N/A User Defined (5-7 Numeric) User Defined (5-7 Numeric) N/A Deny 4 and 8 Digit PIN Deny 4 and 8 Digit PIN N/A Deny Alphanumeric PIN Deny Alphanumeric PIN N/A Passcode 16 Digit Passcode 16 Digit Passcode N/A 4 Digit Password 4 Digit Password N/A Next Tokencode Mode Next Tokencode Mode Next Tokencode Mode N/A On-Demand Authentication On-Demand Authentication On-Demand Authentication N/A On-Demand New PIN On-Demand New PIN N/A Load Balancing / Reliability Testing Failover (3-10 Replicas) Failover N/A Name Locking Enabled Name Locking Enabled No RSA Authentication Manager No RSA Authentication Manager N/A JGS / PAR = Pass = Fail N/A = Non-Available Function RSA Risk-Based Authentication Functionality RSA Native Protocol RADIUS Protocol Risk-Based Authentication Risk-Based Authentication Risk-Based Authentication N/A Risk-Based Authentication with SSO Risk-Based Authentication with SSO N/A JGS = Pass = Fail N/A = Not Applicable to Integration 14
Certification Checklist For RSA Authentication Manager 8.0 Date Tested: December 13, 2013 Certification Environment Product Name Version Operating System RSA Authentication Manager 8.0 Virtual Appliance RSA Authentication Agent API 8.1 Red Hat Linux 5 Ping Identity PingFederate 7.0 Red Hat Linux 5 Mandatory Functionality RSA Native Protocol RADIUS Protocol New PIN Mode Force Authentication After New PIN Force Authentication After New PIN N/A System Generated PIN System Generated PIN N/A User Defined (4-8 Alphanumeric) User Defined (4-8 Alphanumeric) N/A User Defined (5-7 Numeric) User Defined (5-7 Numeric) N/A Deny 4 and 8 Digit PIN Deny 4 and 8 Digit PIN N/A Deny Alphanumeric PIN Deny Alphanumeric PIN N/A Passcode 16 Digit Passcode 16 Digit Passcode N/A 4 Digit Password 4 Digit Password N/A Next Tokencode Mode Next Tokencode Mode Next Tokencode Mode N/A On-Demand Authentication On-Demand Authentication On-Demand Authentication N/A On-Demand New PIN On-Demand New PIN N/A Load Balancing / Reliability Testing Failover (3-10 Replicas) Failover N/A Name Locking Enabled Name Locking Enabled No RSA Authentication Manager No RSA Authentication Manager N/A JGS / PAR = Pass = Fail N/A = Non-Available Function RSA Risk-Based Authentication Functionality RSA Native Protocol RADIUS Protocol Risk-Based Authentication Risk-Based Authentication Risk-Based Authentication N/A Risk-Based Authentication with SSO Risk-Based Authentication with SSO N/A JGS = Pass = Fail N/A = Not Applicable to Integration 15
Known Issues To enable the adapter in a cluster, you must configure PingFederate to use sticky sessions If you plan to deploy the RSA SecurID Adapter in a PingFederate server cluster, you must configure the server s load balancer to use sticky sessions. (For more information about deploying PingFederate in a cluster, see the PingFederate Server Clustering Guide.) PingFederate displays an inaccurate message when a user violates a PIN reuse requirement You may configure an RSA Authentication Manager token policy to restrict users from reusing SecurID PINs. If a user violates a token policy s PIN reuse requirement, the PingFederate client won t instruct the user to choose a unique PIN. Instead, the client will display an Access Denied message, which implies that the user has failed authentication. The user will need to authenticate again before given another chance to set a new PIN. Ping Identity is aware of the issue and plans to address it in a future release. Important: Inform users that if they receive an Access Denied message after they submit a new PIN, they have violated a PIN reuse requirement. Instruct them to authenticate again and choose a unique PIN when prompted. RSA Authentication Manager does not consider this to be a failed authentication attempt. 16
Appendix Partner Integration Details PingFederate Integration Details RSA SecurID API 8.1 RSA Authentication Agent Type Standard Agent RSA SecurID User Support All Users Displays RSA Server Info No Performs Test Authentication Yes Supports Agent Tracing No RSA SecurID Authentication Files Review File Locations Set RSA SecurID Adapter Advanced Options Upload a Node Secret Manually Review File Locations Node Secret: The RSA Authentication Manager node secret is stored in the PingFederate s <pf_home>/pingfederate/server/default/data/adapter-config/ directory in a file named securid. In order clear the node secret: 1. Delete the node secret file (securid) from the adapter-config directory above and log in to the RSA Authentication Manager Security Console. 2. Locate your PingFederate agent in the Authentication Agents table, click the arrow to the right of its hostname and select Manage Note Secret from the dropdown menu. 3. Select the Clear Node Secret checkbox and click the Save button. 4. Return to the PingFederate administrative console and continue configuring the adapter. Important: If the test authentication fails to create a node secret, you must create a new one and install it manually. See the instructions below for details. sdconf.rec: The sdconf.rec file is stored in PingFederate s <pf_home>/pingfederate/server/default/data/adapterconfig/ directory. Use the PingFederate administrative console to manage this file. sdstatus.12: The sdstatus.12 file is stored in PingFederate s <pf_home>/pingfederate/server/default/data/adapterconfig/ directory. sdopts.rec: The sdopts.rec file is stored in PingFederate s <pf_home>/pingfederate/server/default/data/adapterconfig/ directory. Use the PingFederate administrative console to manage this file. 17
Set RSA SecurID Adapter Advanced Options When you click the Show Advanced Fields button on the IdP Adapter configuration screen, the page will expand to display the following optional fields: The table below contains descriptions of each field. See PingFederate documentation for more details. Field Name Description SecurID Node Secret If your test authentication fails to create a node secret, export a new node secret from the RSA Authentication Manager Security Console, save it locally and set the SecurID Node Secret field to its local path. See the directions below for details. SecurID Optional Configuration Challenge Retries Logout Path Logout Redirect Logout Template If you need to upload a SecurID Optional Configuration File (sdopts.rec), save the file in a temporary directory, click the Browse button to the right of the SecurID Optional Configuration field, locate the temporary directory and select the file. If you wish to limit the amount of consecutive failed login attempts the adapter will allow a user before denying access, set the Challenge Retries field to the limit you choose. This value must be less than or equal to any RSA Authentication Manager policy limits. See the RSA Authentication Manager Administrative Guide for information. If your SaaS provider doesn t support SAML Single Log-Out, you can set the Logout Path field to a path on the PingFederate server that will terminate an IdP SSO session after a user logs out of the SaaS provider s service. You may set the Logout Redirect field to a URL on your SP application where the adapter should redirect users to after they log out. The adapter will only use this field if the Logout Path field has been set. You may set the Logout Template field to the name of an HTML template the adapter to display when a user logs out. The template must be stored in the <PF-install>/server/default/conf/template directory. The adapter will only use this field if the Logout Path field is set and either the Logout Redirect field hasn t been set or a logout redirection fails. 18
Upload a Node Secret Manually Follow the instructions below if you need to set the node secret manually: 1. If you are attempting to replace an existing node secret, delete the securid file from the <pf_home>/pingfederate/server/default/data/adapter-config/ directory. 2. Log in to the RSA Authentication Manager Security Console. 3. Locate your PingFederate agent in the Authentication Agents table, click the arrow to the right of its hostname and select Manage Note Secret from the dropdown menu. 4. Check the Create Node Secret checkbox, enter a password in the Encryption Password and Confirm Encryption Password fields and click the Save button. 5. Click the link to download the node secret file (<AgentName>_NodeSecret.zip), save it to a temporary directory and unzip it. You will see a file named nodesecret.rec. 6. Copy the nodesecret.rec file to a temporary directory on your PingFederate server and navigate to that directory from a command line prompt. 7. Issue the following command to load the node secret: /rsa/agent_nsload -f nodesecret.rec -d <pf_home>/pingfederate/server/default/data/adapter-config/ Important: This example assumes that the agent_nsload utility is installed in the /rsa directory on your PingFederate server. If it is installed in another directory, run the command from that directory instead. If you can t locate the utility, contact PingFederate or RSA Customer Support. 8. When prompted for a password, enter the encryption password you set above. 9. Return to the PingFederate s IdP Adapter configuration screen, click the Show Advanced Fields button and set the RSA SecurID Node Secret field. 10. Continue configuring the adapter. 19