EUROPEAN COMMISSION DIRECTORATE-GENERAL INFORMATICS Directorate A - Corporate IT Infrastructure Solutions

Solutions for Information Systems

European Commission Secure Webservices using ECAS For ECAS 1.10 and above

Date:

22/03/2010

Version:

1.1

Authors:

Alain Morlet, Jérôme Hordies

Revised by:

Louis Jacomet, Michaël Manalis

Approved by: Public: Reference Number:

Commission européenne, L-2920 Luxembourg. Telephone: (352) 43 01-1. Commission européenne, B-1049 Bruxelles / Europese Commissie, B-1049 Brussel - Belgium. Telephone: (32-2) 299 11 11. Office: IMCO 3/21. Telephone: direct line (32-2) 2957102. E-mail: [email protected]

TABLE OF CONTENTS 1. INTRODUCTION..................................................................................................................................... 1  1.1. How it works ............................................................................................................................................ 1  2. APPLICATION SERVER CONFIGURATION .................................................................................... 2  2.1. Install the ECAS client for the consumer ................................................................................................. 2  2.2. Install the ECAS client for the Web service ............................................................................................ 2  3. WEB SERVICE ........................................................................................................................................ 3  3.1. Web-service consumer ............................................................................................................................. 3  3.2. Web service.............................................................................................................................................. 4  4. TECHNICAL REFERENCE ................................................................................................................... 6 

TABLE OF FIGURES

Figure 1: Extract of web.xml to setup the ThreadLocal Filter ................................................................ 3  Figure 2: Consumer handler chain configuration example ..................................................................... 3  Figure 3: SOAP request with header example ........................................................................................ 4  Figure 4: Handler chain configuration for Web service .......................................................................... 4  Figure 5: handler chain configuration example ....................................................................................... 5  Figure 6: Web-service response .............................................................................................................. 5 

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page i / i

Document History Version

Author

Date

Comment

1.0

hordije

22/03/2010

Initial draft

1.1

Jacomls

20/04/2010

Formatting and content

Modified Pages

ALL

Reference Documents Code

Title

[ECAS-BASIC]

ECAS Client Installation and Configuration Guide – Basic(*)

[ECAS-ADV]

ECAS Client Installation and Configuration Guide – Advanced(*)

[ECAS-PROXY]

ECAS Client Proxy Guide

[ECAS-FORGE]

http://www.cc.cec/wikis/display/IAM/ECAS+Forge Documents marked with a (*) are available on the Forge

Contact: Jérôme Hordies, Telephone:(32) 2 29-54318, [email protected] Alain MORLET, Telephone:(352) 43 01-35816, [email protected]

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page ii / ii

1. INTRODUCTION This document explains how to use ECAS to secure JAX-WS Web services. The code presented here has been tested on Weblogic server 10gR3. We advise you to read [ECAS-ADV] and [ECAS-PROXY] prior to this document.

Traditional ECAS authentication requires interaction with the user. This is not adequate for application-to-application processes such as Web services. Fortunately, ECAS provides a delegation protocol where the user’s credentials can be delegated to the application. This delegation mechanism is called the proxying of credentials and the delagatee application is called an ECAS Proxy Service. Proxy Services are Web applications protected by ECAS which are able to impersonate the user and send Proxy Tickets on behalf of the user to call back-end target services. The ECAS Proxy protocol is well suited to protect Web services which have latency times inferior to five minutes. In this document, we describe a solution based on 2 basic components: •

A JAX-WS Web service configured with role-based access control.

•

A Web application protected by ECAS that shows how we can invoke the Web service and propagate the user’s identity (using ECAS Proxy Tickets).

We demonstrate what needs to be done on the service side (Web service application) and on the consumer side (Web application) to make things work.

1.1. How it works The Web-service-consumer application authenticates its users using the traditional ECAS mechanism and is configured as a Proxy Service. For each call to the Web service, the application requests a Proxy Ticket and provides it in a conventional SOAP header using a SOAP handler. This way of working has been chosen for two reasons: 1. The ticket is not a part of the Web-service-operation signature and it does not rely on transportspecific mechanisms. Having the ticket not part of the operation parameters allows easier modification of the security mechanism. 2. The SOAP handler chain mechanism makes it easy to manipulate the header of a SOAP request and to implement the security in an aspect-oriented way. Handlers are a kind of filter classes that get executed before sending the request and after receiving the response. On the Web-service side the ECAS authentication handler retrieves the ticket from the conventional header of the SOAP envelope and validates it against ECAS: •

Success: The webservice runs as the authenticated user

•

Failure: A SOAP error is returned to the consumer indicating an authentication failure

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 1 / 1

2. APPLICATION SERVER CONFIGURATION 2.1. Install the ECAS client for the consumer The ECAS client must be configured as a Proxy Service, follow [ECAS-PROXY] in order to do so.

2.2. Install the ECAS client for the Web service The ECAS client must be configured as a Target Service, follow [ECAS-PROXY] in order to do so.

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 2 / 2

3. WEB SERVICE This part describes how to protect a Web service with ECAS. You can find the ECAS demo ear containing a Web service example in the public ECAS subversion repository: http://citnet.cec.eu.int/CITnet/svn/ecas-public/clients/java/trunk/sampleGen/resources/weblogic10.3/webservice/

3.1. Web-service consumer 1. The Web-service-consumer application needs to be protected by ECAS and configured as a Proxy Service in order to call the Web service and propagate the user’s identity. (see [ECASPROXY]) 2. The current implementation requires access to the HttpServletRequest. This access is obtained through a threadlocal set in a Servlet Filter. … … RequestThreadContextFilter eu.cec.digit.ecas.client.webservices.RequestThreadContextFilter RequestThreadContextFilter / …

Figure 1: Extract of web.xml to setup the ThreadLocal Filter

3. The EcasClientSOAPHandler needs to be added to a handler chain wich will be hooked to the Web-service binding. This handler will perform the Proxy-Ticket request using the Principal associated to the service call. This ticket will be added in the SOAP envelope. String WSDLLocation = buildWSDLURL(request); // invoke the webservice URL wsdlUrl = new URL(WSDLLocation); QName qname = new QName("http://examples.webservice/", "HelloService"); HelloService service = new HelloService(wsdlUrl, qname); Hello port = service.getHelloPort(); // Add client-side handlers via JAX-WS API EcasClientSOAPHandler handler = new EcasClientSOAPHandler(); List newHandlerChain = new ArrayList(); newHandlerChain.add(handler); ((BindingProvider) port).getBinding().setHandlerChain(newHandlerChain); LOG.info("About to invoke the service"); String result = port.hello(); LOG.info("Result of webservice: " + result);

Figure 2: Consumer handler chain configuration example

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 3 / 3

As a result, the following SOAP request would be sent: PT-3qmRjWzrCRgKZzsTxzPcQDd0av249pwPHOxY1HwUKzzvjm-8pEzrgPKjelOE57boLx3DuzmKeBzGznQujy9ytWgr8RP0

Figure 3: SOAP request with header example

3.2. Web service 4. As indicated in the introduction, the Web-service endpoint must not be protected by a security constraint in web.xml. 5. Web-services protected by the ECAS client only accept a configuration file called ecas-config.xml where you can set properties needed by the ECAS client such as the one to trust the consumer application(s). See [ECAS-PROXY] for the configuration options of the Target Service. See [ECAS-ADV] for the reference about all the ECAS client properties. 6. The Web service itself needs to have a handler chain configured to use the EcasServerSOAPHandler (provided within the ECAS client). This handler extracts and validates Proxy Tickets from the header of incoming SOAP requests. • If validated, the handler calls the ECAS client to run as the user within the application server. • If not validated, the handler throws an exception resulting in a failed Web-service call for the consumer using a SOAP error indicating the authentication-related cause The SOAP handler configuration file is linked to the Web service with the annotation @HandlerChain. @WebService(targetNamespace = "http://examples.webservice/", name = "Hello", portName = "HelloPort", serviceName = "HelloService") @HandlerChain(file = "HandlerConfig.xml") public class HelloWS { @Resource private WebServiceContext wsContext; @WebMethod public String hello() { StringBuilder message = new StringBuilder(); Subject subject = Security.getCurrentSubject(); // user attributes Set attributes = subject.getPrincipals(WLSUser.class); if (attributes != null) { WLSUser wlsUser = attributes.iterator().next(); UserDetailsAccessible userDetails = (UserDetailsAccessible) wlsUser; message.append("Hello " + userDetails.getFirstName() + " userDetails.getLastName() ); } return message.toString(); } }

"

Figure 4: Handler chain configuration for Web service

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 4 / 4

+

The handler configuration file declares handler-chains, handlers and init parameters. In our case we just need a simple chain with one handler: the EcasServerSOAPHandler. We will not use any init parameter. All the ecas properties needed by the soap handler will be taken from the configuration file ecas-config.xml. EcasServerSOAPHandler eu.cec.digit.ecas.client.webservices.EcasServerSOAPHandler

Figure 5: handler chain configuration example Finally, in our example, the Web service would send the following response: Hello Charles BARTOWSKI

Figure 6: Web-service response

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 5 / 5

4. TECHNICAL REFERENCE You can find the code of the EcasClientSoapHandler here: http://citnet.cec.eu.int/CITnet/svn/ecaspublic/clients/java/trunk/src/java6/webapps/eu/cec/digit/ecas/client/webservices/EcasClientSOAPHan dler.java You can find the code of the EcasServerSoapHandler here: http://citnet.cec.eu.int/CITnet/svn/ecaspublic/clients/java/trunk/src/java6/webapps/eu/cec/digit/ecas/client/webservices/EcasServerSOAPHan dler.java

Secure Webservices using ECAS - For ECAS 1.10 and above Document Version 1.1 dated 22/03/2010

Page 6 / 6