Configuring Security

e-docs > WebLogic Server > Programming WebLogic Web Services > Configuring Security

Programming WebLogic Web Services

Configuring Security

The following sections describe how to configure security for WebLogic Web services:

Overview of Configuring Security

Configuring security for WebLogic Web services is basically no different from securing any other type of application or component that runs on WebLogic Server. You can secure the entire Web service by restricting access to the URLs that invoke the Web service and its WSDL. When you secure the entire Web service, the components that make up the Web service are automatically secured. Or you can secure individual components of the Web service, such as the stateless session EJB, a selected list of its methods, the Web application that contains the web-services.xml file, and so on.

After you secure access to the Web service or some of its components, you configure client applications to use HTTP or SSL to authenticate themselves when they invoke the Web service.

For additional examples of securing WebLogic Web Services, see the Webservice Download Page.

Configuring Security: Main Steps

To configure security for a WebLogic Web service and a client that invokes the service, follow these steps. Later sections describe the steps in detail.

Control access to either the entire Web service or some of its components by creating roles, mapping the roles to principals in your realm, then specifying which components are secured and accessible only by the principals in the role.

See Controlling Access to WebLogic Web Services.
Optionally update the web-services.xml file to specify that the Web service can be accessed only by HTTPS.

See Specifying the HTTPS Protocol.
If your client application will use SSL to authenticate itself, configure SSL for WebLogic Server.

You can configure one-way SSL (the default) where WebLogic Server is required to present a certificate to the client application, or two-way SSL where both the client applications and WebLogic server present certificates to each other.

For details about SSL, the difference between one-way and two-way, and procedures to configure both, see Configuring SSL.

Warning: If you use 2-way SSL to secure the connection when invoking a WebLogic Web Service, WebLogic Server always asserts the identity of the certificate to ensure that it maps to a valid WebLogic Server user, even if the Web Service or the stateless EJB backend component does not require any special privileges. This is not true for 1-way SSL, because in that case the client application does not send its certificate.
Code your client to authenticate itself using HTTP or SSL when invoking a WebLogic Web service.

See Coding a Client Application to Invoke a Secure Web Service.
If your client application is using SSL, configure SSL on the client-side.

See Configuring SSL for a Client Application.

Controlling Access to WebLogic Web Services

As previously discussed, WebLogic Web services are packaged as standard J2EE Enterprise applications. Consequently, to secure access to the Web service, you secure access to some or all of the following standard J2EE components that make up the Web service:

The Web Service URL
The stateless session EJB that implements the Web service
A subset of the methods of the stateless session EJB
The WSDL and Home Page of the Web Service

You can use basic HTTP authentication or SSL to authenticate a client that is attempting to access a WebLogic Web Service. Because the preceding components are standard J2EE components, you secure them by using standard J2EE security procedures.

Note: If the backend component that implements your Web service is a Java class or a JMS listener, the only way to secure the Web service is by adding security constraints to the URL that invokes the Web service, as described in the next section.

For additional and detailed information about configuring, programming, and managing WebLogic security, see the security documentation.

Securing Web Service URL

Client applications use a URL to access a Web service, as described in The WebLogic Web Services Home Page and WSDL URLs. An example of such a URL is:

http://ariel:7001/web_services/TraderService

You can restrict access to the entire Web service by restricting access to its URL. To do this, update the web.xml and weblogic.xml deployment descriptor files (in the Web application that contains the web-services.xml file) with security information.

For detailed information about restricting access to URLs, see Securing WebLogic Resources.

Securing the Stateless Session EJB and Its Methods

If you secure the stateless session EJB that implements a Web Service, client applications that invoke the service have access to the Web application, the WSDL, and the Web Service Home Page, but might not be able to invoke the actual method that implements an operation. This type of security is useful if you want to closely monitor who has access to the business logic of the EJB but do not want to block access to the entire Web Service.

You can also use this type of security to decide at the method-level who has access to the various operations of the Web Service. For example, you can specify that any user can invoke a method that views information, but only a certain subset of users are allowed to update the information.

For more information and procedures about securing EJBs and individual methods of an EJB using the Adminstration Console, see Securing WebLogic Resources.

Securing the WSDL and Home Page of the Web Service

You can restrict access to either the WSDL or Home Page of a WebLogic Web Service by updating the web-services.xml deployment descriptor that describes the service, as described in the following procedure:

Open the web-services.xml file in your favorite editor.

The web-services.xml file is located in the WEB-INF directory of the Web application of the Web Services EAR file. See The Web Service EAR File Package for more information on locating the file.
To restrict access to the WSDL, add the exposeWSDL="False" attribute to the <web-service> element that describes your Web Service. To restrict access to the Home page, add the exposeHomePage="False" attribute. The following excerpt shows an example:
```
     <web-service 
        name="stockquotes" 
        uri="/myStockQuoteService"
        exposeWSDL="False"
        exposeHomePage="False" >
         ...
     </web-service>
```
Re-deploy your Web Service for the change to take affect. The WSDL and Home Page of the Web Service will be inaccessible to all users.

Specifying the HTTPS Protocol

You make a Web service accessible only through HTTPS by updating the protocol attribute of the <web-service> element in the web-services.xml file that describes the Web service, as shown in the following excerpt:

<web-services>
  <web-service name="stockquotes"
               targetNamespace="http://example.com"
               uri="/myStockQuoteService"
               protocol="https" >
     ...
  </web-service>
</web-services>

Note: If you configure SSL for WebLogic Server and you do not specify the HTTPS protocol in the web-services.xml file, client applications can access the Web service using both HTTP and HTTPS. However, if you specify HTTPS access in the web-services.xml file, client applications cannot use HTTP to access the Web service.

If you use the servicegen Ant task to assemble the Web service, use the protocol attribute of the <service> element to specify the HTTPS protocol, as shown in the following sample build.xml file:

<project name="buildWebservice" default="ear">
  <target name="ear">
    <servicegen
       destEar="ws_basic_statelessSession.ear"
       contextURI="WebServices"
       <service
         ejbJar="HelloWorldEJB.jar"
         targetNamespace="http://www.bea.com/webservices/basic/statelesSession"
         serviceName="HelloWorldEJB"
         serviceURI="/HelloWorldEJB"
         protocol="https"
         generateTypes="True"
         expandMethods="True">
       </service>
     </servicegen>
  </target>
</project>

Coding a Client Application to Invoke a Secure Web Service

When you write a JAX-RPC client application that invokes a Web service, you use the following two properties to send a user name and password to the service so that the client can authenticate itself:

javax.xml.rpc.security.auth.username
javax.xml.rpc.security.auth.password

The following example, taken from the JAX-RPC specification, shows how to use these properties when using the javax.xml.rpc.Stub interfaces to invoke a secure Web service:

StockQuoteProviderStub sqp = // ... get the Stub;
sqp._setProperty ("javax.xml.rpc.security.auth.username", "juliet");
sqp._setProperty ("javax.xml.rpc.security.auth.password", "mypassword");
float quote sqp.getLastTradePrice("BEAS");

If you use the WebLogic-generated client JAR file to invoke a Web service, the Stub classes are already created for you, and you can pass the user name and password to the Service-specific implementation of the getServicePort() method, as shown in the following example taken from the JAX-RPC specification:

StockQuoteService sqs = // ... Get access to the service;
StockQuoteProvider sqp = sqs.getStockQuoteProviderPort ("juliet", "mypassword");
float quote = sqp.getLastTradePrice ("BEAS");

In this example, the implementation of the getStockQuoteProvidePort() method sets the two authentication properties.

For additional information on writing a client application using JAX-RPC to invoke a secure Web service, see http://java.sun.com/xml/jaxrpc/index.html.

Configuring SSL for a Client Application

Configure SSL for your client application by using either:

The WebLogic Server-provided SSL implementation
A third-party SSL implementation

If you are using two-way SSL, your client application must also present its certificate to WebLogic Server. For details, see Configuring Two-Way SSL For a Client Application.

For additional detailed information about the APIs discussed in this section see the Web service security Javadocs.

Using the WebLogic Server-Provided SSL Implementation

WebLogic Server provides an implementation of SSL in the webserviceclient+ssl.jar client runtime JAR file. In addition to the SSL implementation, this client JAR file contains the standard client JAX-RPC runtime classes contained in webservicesclient.jar.

Note: For information about BEA's current licensing of client functionality, see the BEA eLicense Web Site.

To configure basic SSL support for your client application, follow these steps:

Copy the file WL_HOME\server\lib\webserviceclient+ssl.jar to your client application development computer, where WL_HOME refers to the top-level directory of WebLogic Platform. This client JAR file contains the client runtime implementation of JAX-RPC as well as the implementation of SSL.
Add the client JAR file to the client application's CLASSPATH variable.
Set the filename of the file containing trusted Certificate Authority (CA) certificates. Do this by either:
- Setting the System property trustedfile to the name of the file that contains a collection of PEM-encoded certificates.
- Executing the BaseWLSSLAdapter.setTrustedCertificatesFile(String ca_filename) method in your client application.
When you run your client application, set the following System properties on the command line:

bea.home=license_file_directory
java.protocol.handler.pkgs=com.certicom.net.ssl

where license_file_directory refers to the directory that contains the BEA license file license.bea, as shown in the following example:

java -Dbea.home=c:\bea_home \
   -Djava.protocol.handler.pkgs=com.certicom.net.ssl  my_app

Note: If your client application is running on a computer different from the computer hosting WebLogic Server (which is typically the case), copy the BEA license file from the server computer to a directory on the client computer, and then point the bea.home System property to this client-side directory.

To disable strict certificate validation, either set the weblogic.webservice.client.ssl.strictcertchecking System property to false at the command line when you run the application, or programmatically use the BaseWLSSLAdapter.setStrictCheckingDefault() method.

For detailed information, see the Web service security Javadocs.

Configuring SSL Programatically

You can also configure the WebLogic Server-provided SSL implementation programatically by using the weblogic.webservice.client.WLSSLAdapter adapter class. This adapter class hold configuration information specific to WebLogic Server's SSL implementation and allows the configuration to be queried and modified.

The following excerpt shows an example of configuring the WLSSLAdapter class for a specific WebLogic Web service; the lines in bold are discussed after the example:

    // instantiate an adapter...
    WLSSLAdapter adapter  = new WLSSLAdapter();
    adapter.setTrustedCertifcatesFile("mytrustedcerts.pem");

    // optionally set the Adapter factory to use this
    // instance always...
    SSLAdapterFactory.getDefaultFactory().setDefaultAdapter(adapter);
    SSLAdapterFactory.getDefaultFactory().setUseDefaultAdapter(true);

    //create service factory
    ServiceFactory factory = ServiceFactory.newInstance();

    //create service
    Service service = factory.createService( serviceName );

    //create call
    Call call = service.createCall();

    call.setProperty("weblogic.webservice.client.ssladapter",
                      adapter);

    try {

      //invoke the remote web service
      String result = (String) call.invoke( new Object[]{ "BEAS" } );
      System.out.println( "Result: " +result);
    } catch (JAXRPCException jre) {
    ...
    }

The example first shows how to instantiate an instance of the WebLogic Server-provided WLSSLAdapter class, which supports the SSL implementation contained in the webserviceclient+ssl.jar file. It then configures the adapter instance by setting the name of the file that contains the Certificate Authority certificates using the setTrustedCertificatesFile(String) method; in this case the file is called mytrustedcerts.pem.

The example then shows how to set WLSSLAdapter as the default adapter of the adapter factory and configures the factory to always return this default.

Note: This step is optional; it allows all Web services to share the same adapter class along with its associated configuration.

You can also set the adapter for a particular Web service port or call. The preceding example shows how to do this when using the Call class to invoke a Web service dynamically:

call.setProperty("weblogic.webservice.client.ssladapter", adapter);

Set the property to an object that implements the weblogic.webservice.client.SSLAdapter interface (which in this case is the WebLogic Server-provided WLSSLAdapter class.)

The following excerpt shows how to set the adapter when using the Stub interface to statically invoke a Web service:

((javax.xml.rpc.Stub)stubClass)._setProperty("weblogic.webservice.client.ssladapter", adapterInstance);

You can get the adapter for a specific instance of a Web service call or port by using the following method for dynamic invocations:

call.getProperty("weblogic.webservice.client.ssladapter");

Use the following method for static invocations:

((javax.xml.rpc.Stub)stubClass)._getProperty("weblogic.webservice.client.ssladapter");

For detailed information, see the Web service security Javadocs.

Using a Third-Party SSL Implementation

If you want to use a third-party SSL implementation, you must first implement your own adapter class. The following example shows a simple class that provides support for JSSE; the main steps to implementing your own class are discussed after the example:

import java.net.URL;
import java.net.Socket;
import java.net.URLConnection;
import java.io.IOException;

public class JSSEAdapter implements weblogic.webservice.client.SSLAdapter {

  javax.net.SocketFactory factory =
    javax.net.ssl.SSLSocketFactory.getDefault();

  // implements weblogic.webservice.client.SSLAdapter interface...

  public Socket createSocket(String host, int port) throws IOException  {
    return factory.createSocket(host, port);
  }

  public URLConnection openConnection(URL url) throws IOException {
    // assumes you have java.protocol.handler.pkgs properly set..
    return url.openConnection();
  }

  // the configuration interface...

  public void setSocketFactory(javax.net.ssl.SSLSocketFactory factory) {
    this.factory = factory;
  }

  public javax.net.ssl.SSLSocketFactory getSocketFactory() {
    return (javax.net.ssl.SSLSocketFactory) factory;
  }
}

To create your own adapter class, follow these steps:

Create a class that implements the following interface:
```
weblogic.webservice.client.SSLAdapter
```
Implement the createSocket method, whose signature is:
```
public Socket createSocket(String host, int port) 
    throws IOException 
```
This method returns an object that extends java.net.Socket. The object is connected to the designated hostname and port when a Web service is invoked.
Implement the openConnection method, whose signature is:
```
public URLConnection openConnection(URL url) throws IOException 
```
This method returns an object that extends the java.net.URLConnection class. The object is configured to connect to the designated URL. These connections are used for infrequent network operations, such as downloading the Web service WSDL.
When you run your client application, set the following System property to the fully qualified name of your adapter class:
```
weblogic.webservice.client.ssl.adapterclass
```
The default SSLAdapterFactory class loads your adapter class and creates an instance of the class using the default no-argument constructor.
Configure your custom adapter class as shown in Configuring SSL Programatically, substituting your class for WLSSLAdapter and using the configuration methods defined for your adapter.

For detailed information, see the Web service security Javadocs.

Extending the SSLAdapterFactory Class

You can create your own custom SSL adapter factory class by extending the SSLAdapterFactory class, which is used to create instances of adapters. One reason for extending the factory class is to allow custom configuration of each adapter when it is created, prior to use.

To create a custom SSL adapter factory class, follow these steps:

Create a class that extends the following class:
```
weblogic.webservice.client.SSLAdapterFactory
```
Override the following method of the SSLAdapterFactory class:

public weblogic.webservice.client.SSLAdapter createSSLAdapter();

This method is called whenever a new SSLAdapter, or an adapter that implements this interface, is created by the adapter factory. By overriding this method, you can perform custom configuration of each new adapter before it is actually used.

In your client application, create an instance of your factory and set it as the default factory by executing the following method:

SSLAdapterFactory.setDefaultFactory(factoryInstance);

For detailed information, see the Web service security Javadocs.

Configuring Two-Way SSL For a Client Application

If you configured two-way SSL for WebLogic Server, the client application must present a certificate to WebLogic Server, in addition to WebLogic Server presenting a certificate to the client application as required by one-way SSL. The following sample Java code shows one way of doing this where the client application receives the client certificate file as an argument (relevant code in bold):

...

SSLAdapterFactory factory = SSLAdapterFactory.getDefaultFactory();
WLSSLAdapter adapter = (WLSSLAdapter) factory.getSSLAdapter();

if (argv.length > 1 ) {
  System.out.println("loading client certs from "+argv[1]);

FileInputStream clientCredentialFile  = new FileInputStream (argv[1]);
String pwd = "clientkey";

adapter.loadLocalIdentity(clientCredentialFile, pwd.toCharArray());

javax.security.cert.X509Certificate[] certChain = adapter.getIdentity("RSA",0);

factory.setDefaultAdapter(adapter);

factory.setUseDefaultAdapter(true);

...

For a complete example of using two-way SSL with WebLogic Web Services, see the Two-Way SSL Example.

Using a Proxy Server

If your client application is running inside a firewall, for example, and needs to use a proxy server, set the host name and the port of the proxy server using the following two System properties:

weblogic.webservice.transport.https.proxy.host
weblogic.webservice.transport.https.proxy.port

For more information on these System properties, see WebLogic Web Services System Properties.