Software Design Document Securing Web Service with Proxy

Software Design Document Securing Web Service with Proxy Federated Access Manager 8.0 Version 0.3 Please send comments to: dev@opensso.dev.java.net This document is subject to the following license: COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL) Version 1.0 http://www.opensource.org/licenses/cddl1.php

Contents 1 Introduction...1 1.1 Document Status...1 1.2 Revision History...1 1.3 Summary...1 1.4 Scope...1 1.5 Context...2 1.6 Glossary...2 1.7 References...2 2 Overview...5 3 Design Considerations...7 3.1 Assumptions and Dependencies...7 3.2 Goals and Guidelines...7 3.3 Development Method...7 4 Architectural Strategies...8 4.1 Limitations...8 5 System Architecture...9 6 Detailed System Architecture...11 6.1 Performance...14 6.2 Installation...15 7 Appendices...16 7.1 Appendix-A: AMConfig.properties template...16 Copyright 2007 Sun Microsystems, Inc. All rights reserved. iii

1 Introduction 1.1 Document Status Project Name Federated Access Manager 8.0 Document Title Securing Web Service with Proxy Date of Issue 07/11/07 Current Version 0.3 Author Dennis Seah (dennis.seah@sun.com) Issuing Organization Sun Microsystems, Inc. Feedback E-mail dev@opensso.dev.java.net 1.2 Revision History Date Version Author Comments 07/11/07 0.1 Dennis Seah Initial Draft 07/20/07 0.2 Dennis Seah Incorporated Feedback from Mrudul add more information of configuration of WS Proxy add limitations of WS Proxy as compared to container specific WSS Providers 07/25/07 0.3 Dennis Seah Incorporated Feedback from FAM-WSS team members add more information on how performance figures are gathered add information on how to handle agent profile from sub realm. alter section on Configuration to handle AMConfig.properties the same way as other WSS plugin setups. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 1

Securing Web Service with Proxy, Version Introduction 1.3 Summary This document describes the design details of securing web service with a web proxy which uses Federated Access Manager's Web Service Security APIs. 1.4 Scope This document is limited to the design aspects of web proxy which is to secure web service. It does not include information on Federated Access Manager's Web Service Security Core API implementations. It also do not contain information on how tosecure the communication channels between WSC/WSP and proxy. 1.5 Context This document is written for architects, OpenSSO developers and QA engineers. Readers should understand the Web-Tier on Java Enterprise Edition (JavaEE) specification; and familiar with the Federated Access Manager's Web Service Security Core APIs. 1.6 Glossary API FAM JAX-RPC JAX-WS JavaEE OpenSSO SOAP STS WSDL WS WSC Application Programming Interface Federated Access Manager Java API for XML-Based RPC Java API for XML-Based Web Services Java Enterprise Edition Open Source - Single Sign On. An open source project funded by Sun Microsystems Inc to provide secure single sign on solutions Simple Object Access Protocol Security Token Service Web Service Definition Language Web Service Web Service Client 2 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Introduction Securing Web Service with Proxy, Version 0.3 WSP WSS Web Service Provider Web Service Security 1.7 References [1] Web Service Security Software Requirement Specification by Mrudul Uchil [2] WSS framework & SWS on Glassfish Software Design Document by Mrudul Uchil [3] Security Token Service Software Design Document by Mrudul Uchil [4] Web Service Security for Weblogic Software Design Document by Malla Simhachalam and Hua Cui Copyright 2007 Sun Microsystems, Inc. All rights reserved. 3

2 Overview Web Service is widely used to integrate web based applications. SOAP is used to transfer request and response between WSC and WSP. This document describes a way to secure the WS request and response when we do not have control over the WSC's and/or WSP's deployment environment. And/Or, when there are no common WS-Security mechanisms between WSC and WSP (in cases when STS cannot be used). This way of securing web security shall work for both JAX-RPC and JAX-WS. Essentially, we introduce a web application (into the WS deployment environment) which acts as proxy to secure WS messages. Followings are the possible setup. 1. WSC and WSP rely on proxy to secure WS messages. Figure 1: WSC Proxy and WSP Proxy 2. WSC relies on proxy to secure WS request and validate WS response. WSP already has the ability to validate WS request and secure WS response. Figure 2: WSC with Proxy 3. WSC already has the ability to secure WS request and validate WS response. WSP relies on proxy to validate WS request and secure WS response. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 5

Securing Web Service with Proxy, Version Overview Figure 3: WSP with Proxy 6 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Design Considerations Securing Web Service with Proxy, Version 0.3 3 Design Considerations 3.1 Assumptions and Dependencies Some application servers do not provide security mechanisms for securing WS request and response. Or if they do, WSC and WSP may not have any common security mechanisms. The WS-Security Proxy is dependent on FAM s Web Service Security APIs and also FAM s IdRepo API (for fetching WSC and WSP profiles). 3.2 Goals and Guidelines The goal is to secure WS request and response that works on all application servers in a least intrusive manner. The benefits of this approach are 1. Works for all application servers 2. Do not require change on WSP deployment. 3. Minimum changes to WSC s WSDL. 3.3 Development Method We are adopting OpenSSO Development Method. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 7

Securing Web Service with Proxy, Version Architectural Strategies 4 Architectural Strategies The WS-Security Proxy uses FAM s Web Service Security APIs for securing WS request and response; and to validate them. And, it also uses FAM s remote IdRepo API to read WSC Agent s and WSP Agent s profile to obtain the WSP End point. The strategy is to route the WS SOAP messages (request and response) through the WS-Security Proxy; and have the proxy to secure and validate the messages. Since proxy does not share the same JVM space with the WSC and WSP; and it is agnostic to the type of messages (can be JAX-RPC or JAX-WS) that it is operating on, WS-Security Proxy provides a least intrusive way to secure WS messages. 4.1 Limitations There are some limitations to this WS-Security Proxy approach and they are 1. One has to make sure that the communication channel between and WSC and WSC s Proxy; and WSP s Proxy and WSP are secured. 2. WS Proxy would be not be able take advantage of "Subject" that is being set within the container: WSC Proxy would not be able set the security token based on the "Subject" WSP Proxy would not be able to set the "Subject" 8 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

System Architecture Securing Web Service with Proxy, Version 0.3 5 System Architecture Below are the high level architecture diagram and event sequence diagram. Figure 4: High Level Architecture Diagram Figure 5: Event Sequence Diagram [1] WSC makes a WS request through its WS-Security Proxy. [2] WSC s Proxy makes a FAM s remote IdRepo call to get the WSP s WS end point (in this case, it is the WS-Security Proxy on the WSP end). [3] WSC s Proxy calls the FAM s WS-Security API to secure the WS Request and then send (with HttpURLConnection) the secured message to the WSP s Proxy. [4] WSP s Proxy makes a FAM s remote IdRepo call to get the WSP s WS end point. [5] WSP s Proxy validates the secured WS Request before sending the WS Request (with HttpURLConnection) to the WSP. [6] WSP processes the request and return the WS Response to WSP s Proxy. [7] WSP s Proxy calls the FAM s WS-Security API to secure the WS Response and then send (with HttpURLConnection) the secured message to the WSC s Proxy. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 9

Securing Web Service with Proxy, Version System Architecture [8] WSC s Proxy validates the secured WS Response before returning it to the WSC. 10 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Detailed System Architecture Securing Web Service with Proxy, Version 0.3 6 Detailed System Architecture Followings are the main components in the system. 1. Web Service Client, WSC WSC is the component that request for a service from the WSP using JAX-RPC or JAX-WS protocol. In this WS-Security Proxy approach, WSC contacts the WSC s Proxy to get the WSP s WSDL (instead of contacting WSP directly). The diagram below illustrates this. Figure 6: Sequence Diagram for fetching WSDL [1] WSC contacts WSC s Proxy for WSP s WSDL e.g. http://wscproxy.sample.com:8080/wsproxy/securityproxy/wsc?wsdl= [2] WSC s Proxy contacts FAM to get the WSP s endpoint (in the case, it is the WSP s Proxy). The last token of the URL is used to determine the WS-Security agent Id. In this case, it is wsc. [3] WSC s Proxy contacts WSP s Proxy for WSDL e.g. http://wspproxy.sample.com:8080/wsproxy/securityproxy/wsp?wsdl [4] WSP s Proxy contacts FAM to get the WSP s endpoint. The last token of the URL is used to determine the WS-Security agent Id. In this case, it is wsp. [5] WSP s Proxy contacts WSP for WSDL [6] WSP provides the WSDL [7] WSP s Proxy alters the soap-address in the WSDL to its URL. e.g. http://wspproxy.sample.com:8080/wsproxy/securityproxy/wspbefore returning it to WSC s proxy. [8] WSC s Proxy alters the soap-address in the WSDL to its URL. e.g. http://wscproxy.sample.com:8080/wsproxy/securityproxy/wsc before returning it to WSC. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 11

Securing Web Service with Proxy, Version Detailed System Architecture Note that the WSDL is altered in the manner that WS Request will be routed to WSC s Proxy automatically. 2. Web Service Provider, WSP WSP is the component that provide services to WSC using JAX-RPC or JAX-WS protocol. In this proxy approach, WSP needs not be altered. 3. Web Service Client Proxy, WSC s Proxy In Figure 5, we illustrated how WSC s Proxy secures WS request and validate WS response. And, in Figure 6, we illustrated how it fetches WSDL. 4. Web Service Provider Proxy, WSC s Proxy In Figure 5, we illustrated how WSP s Proxy secures WS response and validate WS request. And, in Figure 6, we illustrated how it fetches WSDL. 5. FAM Federated Access Manager provides the WS-Security API for securing WS request and response; and validate them. And, provides remote IdRepo API for accessing WS-Security agent profiles. Up to this point, we have provided a succinct view of how WS-Security Proxy. With this as the baseline, we shall further describes the WS-Security Proxy in details. WS-Security Proxy is an Java EE web application. It comprises of these major objects. 1. WEB-INF/web.xml 2. WEB-INF/classes/AMConfig.properties 3. WEB-INF/classes/com/sun/identity/w s/proxy/securityproxy.class 4. WEB-INF/lib/amclientsdk.jar 5. WEB-INF/lib/fmclientsdk.jar 6. WEB-INF/lib/ldapjdk.jar This is how the web.xml looks like 12 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Detailed System Architecture Securing Web Service with Proxy, Version 0.3 <?xml version="1.0" encoding="utf-8"?> <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:schemalocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> <servlet> <servlet-name>securityproxy</servlet-name> <servlet-class>com.sun.identity.wss.proxy.securityproxy</servlet-class> </servlet> <servlet-mapping> <servlet-name>securityproxy</servlet-name> <url-pattern>/securityproxy</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file> index.jsp </welcome-file> </welcome-file-list> </web-app> AMConfig.properties contains configuration information on how to communicate with FAM. SecurityProxy.class is the implementation of the WS-Security Proxy. It is a servlet. Followings are the pseudo code for the main method in SecurityProxy.class //doget and dopost calls the processrequest method void processrequest { String contenttype = request.getcontenttype(); String wsdl = request.getparameter("wsdl"); if (wsdl!= null) { processwsdlrequest } else if ((contenttype!= null) && (contenttype.indexof("text/xml")!= -1) ) { processwsrequest } else { Copyright 2007 Sun Microsystems, Inc. All rights reserved. 13

Securing Web Service with Proxy, Version Detailed System Architecture } } printsevletdescription void processwsdlrequest { getwspendpointwithagentid (AgentId is derived from URL. e.g. /wsc from http://.../securityproxy/wsc) open URLConnection and fetch WSDL alter the soap-address to servlet URL write the WSDL back to the response. } void processwsrequest { getwspendpointwithagentid getsoapmessage from request object. getagentprofile to determine if this proxy is a WSC's Proxy or WSP's. if (WSC's proxy) securerequest else validaterequest open URLConnection with WSPEndPoint and post the SOAP Message get the result from the Post if (WSC's proxy) validateresponse else secureresponse write the resulting SOAP message back to the original response. } 6.1 Performance Performance is an issue with this WS-Security Proxy approach because there is an extra XML parsing involved in the process of securing the message. From our prototype, here is the result that we have gotten. 14 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Detailed System Architecture Securing Web Service with Proxy, Version 0.3 Machine Configuration: Sun-Blade 2500 (1.6-GHz UltraSPARC IIIi processors) Running Solaris 10 Running Glassfish (Sun Java System Application Server 9.1 (build b41d-beta2)) Running Access Manager 7.1 Sequence 100 web service calls. Results are shown in seconds. WSS Setup/Sec. Mech. Anonymous SAML HolderOfKey User Token X509Token G-WSC + G-WSP 33 55 36 50 G-WSC + WSP-Proxy 20 50 36 50 WSC-Proxy + G-WSP 33 47 32 60 WSC-Proxy + WSP-Proxy 20 45 28 44 G-WSC: Glassfish WSS Provider on WSC end G-WSP: Glassfish WSS Provider on WSP end 6.2 Installation Followings are the steps to configure WS-Security Proxy. 1. Create AMConfig.properties and include it in WEB-INF/classes directory of the WS-Security Proxy war fie. See Appendix-A for AMConfig.properties template. The following values need to be obtained from user to tag swap this template. This will be done consistently with other WS- Security plugins that are shipped with FAM. 2. Deploy the WAR. 3. Create WSC and WSP profiles 4. For existing WSC, alter the WSDL s soap-address in WSC s WSDL to point to the WS-Security Proxy. For new WSC, use WS-Security to query for WSP s WSDL. Copyright 2007 Sun Microsystems, Inc. All rights reserved. 15

Securing Web Service with Proxy, Version Appendices 7 Appendices 7.1 Appendix-A: AMConfig.properties template The following keys are used to configure the Debug service. * Possible values for the key 'level' are: off error warning message. * The key 'directory' specifies the output directory where the debug files * will be created. * Trailing spaces are significant. * Windows: Use forward slashes "/" separate directories, not backslash "\". * Windows: Spaces in the file name are allowed for Windows. com.iplanet.services.debug.level=error com.iplanet.services.debug.directory=@debug_dir@ * Naming URL com.iplanet.am.naming.url=@naming_url@ * Notification URL com.iplanet.am.notification.url= * Security Credentails to read the configuration data com.sun.identity.agents.app.username=urlaccessagent com.iplanet.am.service.password=@application_passwd@ com.iplanet.am.service.secret=@encoded_application_password@ * Encryption key that will be used to encrypt and decypt * data to communicate with the server. * This key is needed to decrypt passwords stored * in the SMS configuration. am.encryption.pwd=@encryption_key@ * Encryption key that will be used to encrypt and decypt * data used locally within the client. com.sun.identity.client.encryptionkey=@encryption_key_local@ * Encryption: The key "com.iplanet.security.encryptor" specifies * the encrypting class implementation. * Available classes are: * com.iplanet.services.util.jceencryption * com.iplanet.services.util.jssencryption 16 Copyright 2007 Sun Microsystems, Inc. All rights reserved.

Appendices Securing Web Service with Proxy, Version 0.3 com.iplanet.security.encryptor=com.iplanet.services.util.jceencryption * Property to enable/disable the notifications for am.sdk and IdRepo Caches. * If set to "true" notifications are enabled and disabled if set to "false". com.sun.identity.idm.remote.notification.enabled=true * Cache update time (in minutes) for am.sdk & IdRepo Caches * if notification URL is not provided or if notifications are disabled. * Note: * 1. This property is applicable only if 'com.iplanet.am.notification.url' * is not provided or if 'com.sun.identity.idm.remote.notification.enabled' * is set to 'false'. * 2. If the polling time is set as 0, then polling is disabled. com.iplanet.am.sdk.remote.pollingtime=1 * Property to enable/disable the notifications for service management caches. * If set to "true" notifications are enabled and disabled if set to "false". com.sun.identity.sm.notification.enabled=true * Cache update time (in minutes) for service configuration data, * if notification URL is not provided or if notifications are disabled. * Note: * 1. This property is applicable only if 'com.iplanet.am.notification.url' * is not provided or if 'com.sun.identity.sm.notification.enabled' is * set to 'false'. * 2. If the cache time is set as 0, then no cache updates will occur. com.sun.identity.sm.cachetime=1 * Server protocol, host and port to be used by Authentication Service com.iplanet.am.server.protocol=@server_protocol@ com.iplanet.am.server.host=@server_host@ com.iplanet.am.server.port=@server_port@ com.iplanet.am.cookie.name=iplanetdirectorypro * Session related properties. com.iplanet.am.session.client.polling.enable=true com.iplanet.am.session.client.polling.period=180 * Supported SOAP actors. Each actor must be seperated by ' ' com.sun.identity.liberty.ws.soap.supportedactors=http://schemas.xmlsoap.org/soap/actor/next Copyright 2007 Sun Microsystems, Inc. All rights reserved. 17

Securing Web Service with Proxy, Version Appendices 18 Copyright 2007 Sun Microsystems, Inc. All rights reserved.