Transport-level security refers to securing the connection between a client application and a Web service with Secure Sockets Layer (SSL) or HTTP Basic authentication, either alone or in combination.
SSL provides secure connections by allowing two applications connecting over a network to authenticate the other's identity and by encrypting the data exchanged between the applications. Authentication allows a server, and optionally a client, to verify the identity of the application on the other end of a network connection. A client certificate (two-way SSL) can be used to authenticate the user.
See Secure Sockets Layer (SSL) in Oracle Fusion Middleware Understanding Security for Oracle WebLogic Server for general information about SSL and the implementations included in WebLogic Server.
The following sections describe how to configure transport-level security for your Web service:
You can specify a policy that requires SSL, HTTP BASIC authentication, or both.
If the policy requires SSL, make sure you configure SSL for the core WebLogic Server security subsystem. You can configure one-way SSL 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.
To configure two-way or one-way SSL for the core WebLogic Server security subsystem, see Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server.
For example, the Oracle-supplied Wssp1.2-2007-Saml2.0-Bearer-Https.xml policy file includes the following assertion indicating that the policy is expecting a client certificate via SSL, as shown in Example 3-1.
Example 3-1 Specifying SSL in a Policy
<sp:TransportToken> <wsp:Policy> <sp:HttpsToken/> </wsp:Policy> </sp:TransportToken>
If two-way SSL is required, also use the RequireClientCertificate assertion, as shown in Example 3-2.
Example 3-2 Two-Way SSL in a Policy
<sp:TransportToken> <wsp:Policy> <sp:HttpsToken > <wsp:Policy> <sp:RequireClientCertificate/> </wsp:Policy> </sp:HttpsToken> </wsp:Policy> </sp:TransportToken>
The Wssp1.2-2007-Https-BasicAuth.xml policy file requires both a client certificate via SSL and HTTP BASIC Authentication, as shown in Example 3-3.
Example 3-3 SSL and HTTP Basic Authentication in a Policy
<sp:TransportToken> <wsp:Policy> <sp:HttpsToken> <wsp:Policy> <sp:HttpBasicAuthentication/> </wsp:Policy> </sp:HttpsToken> </wsp:Policy> </sp:TransportToken>
To configure transport-level Web services security via one or more policy files:
Configure SSL for the core WebLogic Server security subsystem.
You can configure one-way SSL 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.
To configure two-way or one-way SSL for the core WebLogic Server security subsystem, see Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server.
Use @Policy or @Policies JWS annotations in your JWS file, or associate policy files only at runtime using the Administration Console, or specify some policy files using the annotations and then associate additional ones at runtime.
Note:
If you specify a transport-level security policy for your Web service, it must be at the class level.In addition, the transport-level security policy must apply to both the inbound and outbound directions. That is, you cannot have HTTPS for inbound and HTTP for outbound.
If you added @Policy or @Policies JWS annotations in your JWS file, compile and redeploy your Web service as part of the normal iterative development process.
When you run the client application that invokes the Web service, specify certain properties to indicate the SSL implementation that your application should use. In particular:
To specify the Certicom SSL implementation, use the following properties
-Djava.protocol.handler.pkgs=weblogic.net -Dweblogic.security.SSL.trustedCAKeyStore=trustStore
where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate). To disable host name verification, also specify the following property:
-Dweblogic.security.SSL.ignoreHostnameVerification=true
To specify Sun's SSL implementation, use the following properties:
-Djavax.net.ssl.trustStore=trustStore
where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate). To disable host name verification, also specify the following property:
-Dweblogic.wsee.client.ssl.stricthostchecking=false
See Configuring Two-Way SSL for a Client Application for details about two-way SSL.
If you specify a transport-level security policy for your Web service, it must be at the class level, as shown in the following example.
Transport-level policy at the class level
@Policy(uri="policy:Wssp1.2-2007-Saml2.0-Bearer-Https.xml")
public class EchoService {
....
This section describes a simple example for configuring JAX-WS with Transport Security from a standalone client for one-way SSL.
See the following documentation for additional prerequisite information:
Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server
"Configure SSL" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help
"Configure KeyStores" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Help
The Web service Java source is shown in Example 3-4:
Note:
If you specify a transport-level security policy for your Web service, it must be at the class level.In addition, the transport-level security policy must apply to both the inbound and outbound directions. That is, you cannot have HTTPS for inbound and HTTP for outbound.
Example 3-4 Web Service One-Way SSL Example
package httpbasicauth
import javax.jws.WebMethod;
import javax.jws.WebService;
import weblogic.jws.Policy;
@WebService(name="HttpsBasicAuth", portName="HttpsBasicAuthSoapPort"
targetNamespace="https://httpsbasicauth")
// Security Policy for Https and Http Basic Authentication
@Policy(uri = "policy:Wssp1.2-2007-Https-BasicAuth.xml)
public class HttpsBasicAuth {
public HttpsBasicAuth() {}
WebMethod()
public String echoString(String input) {
return("[HttpsBasicAuth.echoString]: " + input);
}
}
The standalone Java Web service client code that uses "weblogic.net" as the Java protocol handler is shown in Example 3-5:
Example 3-5 Web Service Client One-Way SSL Example With weblogic.net
package httpbasicauth.client
import java.net.URL;
import java.security.cert.X509Certificate;
import java.util.Map;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import httpsbasicauth.client.HttpsBasicAuthService;
import httpsbasicauth.client.HttpsBasicAuth;
public class HttpsBasicAuthClient
private final static String ENDPOINT = .....;
private final static String TARGET_NAMESPACE = "https://httpsbasicauth
private final static String USERNAME = ....;
private final static String PASSWORD = ....;
private final static String TRUST_STORE_LOCATION = .....;
private final static String TARGET_NAMESPACE = ....;
private HttpsBasicAuthService service;
private HttpsBasicAuth stub;
public HttpsBasicAuthClient() {
try {
// This ignores the host name verifcation for the Public Certificate used by the Server
System.setProperty("weblogic.security.SSL.ignoreHostnameVerification","true");
System.setProperty("java.protocol.handler.pkgs", "weblogic.net");
System.setProperty("weblogic.security.TrustKeyStore","CustomTrust");
System.setProperty("weblogic.security.CustomTrustKeyStoreFileName", "TRUST_STORE_LOCATION");
System.setProperty("weblogic.security.CustomTrustKeyStorePassPhrase","TRUST_STORE_PASSWORD");
System.setProperty("weblogic.security.CustomTrustKeyStoreType","JKS");
URL url = new URL(endpoint+"?WSDL");
QName serviceName = new QName(TARGET_NAMESPACE, "HttpsBasicAuthService");
service = new HttpsBasicAuthService();
stub = service.getHttpsBasicAuthSoapPort();
BindingProvider bp = (BindingProvider) stub;
Map<String,Object> context = bp.getRequestContext();
context.put(BindingProvider.USERNAME_PROPERTY, USERNAME)
context.put(BindingProvider.PASSWORD_PROPERTY, PASSWORD);
context.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ENDPOINT);
} catch (Exception e) {
System.out.println("Error in creating the stub : " + e.getMessage());
if (verbose) e.printStackTrace();
}
}
public void invokeEchoString() throws Exception {
String output = stub.echoString(ENDPOINT);
System.out.println("[HttpsBasicAuthClient.invokeGEchoString]: " + output);
}
public static void main(String[] argv) throws Exception {
HttpsBasicAuthClient client = new HttpsBasicAuthClient();
System.setProperty("weblogic.wsee.verbose","*");
System.out.println("----------------------");
System.out.println(" Invoking echoString ");
client.invokeEchoString();
}
}
The standalone Java Web service client code that uses the default Java protocol handler is shown in Example 3-6:
Example 3-6 Web Service Client One-Way SSL Example With java.net
package httpbasicauth.client
import java.net.URL;
import java.security.cert.X509Certificate;
import java.util.Map;
import javax.xml.namespace.QName;
import javax.xml.ws.BindingProvider;
import httpsbasicauth.client.HttpsBasicAuthService;
import httpsbasicauth.client.HttpsBasicAuth;
public class HttpsBasicAuthClient
private final static String ENDPOINT = .....;
private final static String TARGET_NAMESPACE = "https://httpsbasicauth
private final static String USERNAME = ....;
private final static String PASSWORD = ....;
private final static String TRUST_STORE_LOCATION = .....;
private final static String TARGET_NAMESPACE = ....;
private HttpsBasicAuthService service;
private HttpsBasicAuth stub;
public HttpsBasicAuthClient() {
try {
System.setProperty("java.protocol.handler.pkgs", "java.net");
System.setProperty("javax.net.ssl.trustStore", TRUST_STORE_LOCATION);
System.setProperty("javax.net.ssl.trustStorePassword", TRUST_STORE_PASSWORD);
URL url = new URL(ENDPOINT+"?WSDL");
QName serviceName = new QName(TARGET_NAMESPACE, "HttpsBasicAuthService");
service = new HttpsBasicAuthService();
stub = service.getHttpsBasicAuthSoapPort();
BindingProvider bp = (BindingProvider) stub;
Map<String,Object> context = bp.getRequestContext();
context.put(BindingProvider.USERNAME_PROPERTY, USERNAME)
context.put(BindingProvider.PASSWORD_PROPERTY, PASSWORD);
context.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, ENDPOINT);
} catch (Exception e) {
System.out.println("Error in creating the stub : " + e.getMessage());
if (verbose) e.printStackTrace();
}
}
public void invokeEchoString() throws Exception {
String output = stub.echoString(ENDPOINT);
System.out.println("[HttpsBasicAuthClient.invokeGEchoString]: " + output);
}
public static void main(String[] argv) throws Exception {
HttpsBasicAuthClient client = new HttpsBasicAuthClient();
System.setProperty("weblogic.wsee.verbose","*");
System.out.println("----------------------");
System.out.println(" Invoking echoString ");
client.invokeEchoString();
}
}
The related portion of the ant build file is shown in Example 3-7:
<property name="output.dir" value="../../build/httpsbasicauth" />
<property name="service.dir" value="${output.dir}/httpsbasicauthApp" />
<property name="output.dir.client" value="${output.dir}/client" />
<property name="clientclasses.dir" value="${output.dir}/client" />
<property name="service.name" value="HttpsBasicAuth" />
<property name="wsdl.name" value="HttpsBasicAuthService" />
<property name="packageName" value="httpsbasicauth.client" />
<path id="client.class.path">
<pathelement path="${java.class.path}" />
<pathelement path="${clientclasses.dir}" />
</path>
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<taskdef name="jwsc" classname="weblogic.wsee.tools.anttasks.JwscTask"/>
<target name="jwsc">
<jwsc srcdir="." destdir="${output.dir.server}" sourcepath="../" debug="true" keepGenerated="true">
<module name="HttpsBasicAuth" contextPath="httpsbasicauth">
<jws file="HttpsBasicAuth.java" type="JAXWS" generateWsdl="true">
<WLHttpTransport contextPath="httpsbasicauth" serviceUri="httpsbasicauth"/>
</jws>
</jwsc>
</target>
<target name="client">
<clientgen wsdl="jar:file:${service.dir}/${service.name}.war!/WEB-INF/${wsdl.name}.wsdl"
type="JAXWS"
destDir="${clientclasses.dir}"
packageName="${packageName}">
</clientgen>
<javac srcdir="${clientclasses.dir}"
destdir="${clientclasses.dir}"
includes="**/*.java"
classpathref="client.class.path" />
<javac srcdir="./"
destdir="${clientclasses.dir}"
includes="HttpsBasicAuthClient.java"
classpathref="client.class.path" />
</target>
<target name="run">
<java classname="httpsbasicauth.client.HttpsBasicAuthClient"
classpathref="client.class.path"
fork="true" />
</target>
JAX-RPC clients can use the SSLAdapter mechanism described in Using a Custom SSL Adapter with Reliable Messaging to persist the state of a request over an SSL connection. In doing so, they persist the instance of the custom SSLAdapter used to establish the connection.
This release of Oracle WebLogic Server includes a new two-way SSL client API for JAX-WS that you can use to construct an SSLSocketFactory from system properties or from a new weblogic.wsee.jaxws.sslclient.PersistentSSLInfo class. The API can persist SSL info for Reliable Messaging, callbacks, and so forth, and supports the following well-known system properties:
weblogic.wsee.client.ssl.relaxedtrustmanager
weblogic.security.SSL.ignoreHostnameVerification
The following new classes are available. See the Javadoc for complete descriptions.
weblogic.wsee.jaxws.sslclient.SSLClientUtil. This class has the following methods:
public static SSLSocketFactory getSSLSocketFactory(KeyManager[] kms, TrustManager[] tms);
public static SSLSocketFactory getSSLSocketFactory(PersistentSSLInfo sslInfo);
public static SSLSocketFactory getSSLSocketFactoryFromSysProperties();
weblogic.wsee.jaxws.sslclient.PersistentSSLInfo, a Javabean for setting SSL info.
weblogic.wsee.jaxws.JAXWSProperties, includes a CLIENT_PERSISTENT_SSL_INFO property.
Example 3-8 shows an example of getting the SSLSocketFactory from system properties and using them in the request context.
Note:
The clientKeyStore and clientKeyStorePasswd have this restriction: the SSL package of J2SE requires that the password of the client's private key must be the same as the password of the client's keystore. For this reason, the client keystore can include only one private key and X.509 certificate pair.Example 3-8 Getting SSLSocketFactory From System Properties
String clientKeyStore = ...;
String clientKeyStorePasswd = ...;
String trustKeystore = ...;
String trustKeystorePasswd = ...;
System.setProperty("javax.net.ssl.keyStore", clientKeyStore);
System.setProperty("javax.net.ssl.keyStorePassword", clientKeyStorePasswd);
System.setProperty("javax.net.ssl.trustStore", trustKeystore);
System.setProperty("javax.net.ssl.trustStorePasswd", trustKeystorePasswd);
((BindingProvider) port).getRequestContext().put(
JAXWSProperties.SSL_SOCKET_FACTORY,
SSLClientUtil.getSSLSocketFactoryFromSysProperties());
Example 3-9 shows an example of getting SSLSocketFactory from persistent info (PersistentSSLInfo), as well as directly setting a SSLSocketFactory if persistence is not needed.
Example 3-9 Getting SSLSocketFactory from PersistentSSLInfo
String clientKeyStore = ...;
String clientKeyStorePasswd = ...;
String clientKeyAlias = ...;
String clientKeyPass = ...;
String trustKeystore = ...;
String trustKeystorePasswd = ...;
PersistentSSLInfo sslInfo = new PersistentSSLInfo();
sslInfo.setKeystore(clientKeyStore);
sslInfo.setKeystorePassword(clientKeyStorePasswd);
sslInfo.setKeyAlias(clientKeyAlias);
sslInfo.setKeyPassword(clientKeyPass);
sslInfo.setTrustKeystore(trustKeystore);
//user can print out the sslInfo for debug
System.out.print(sslInfo.toString());
//Put sslInfo into requestContext for persistence, it might be required by JAX-WS
advance features, such as, RM, Callback
((BindingProvider) port).getRequestContext().put(
JAXWSProperties.CLIENT_PERSISTENT_SSL_INFO, sslInfo);
//Alternatively, you can directly set a SSLSocketFactory if persistence is
not necessary. Note: The following line should be omitted if sslInfo is set with
above line.
((BindingProvider) port).getRequestContext().put(
JAXWSProperties.SSL_SOCKET_FACTORY,
SSLClientUtil.getSSLSocketFactory(sslInfo));
sslInfo can set a key alias (clientKeyAlias) that points to a key in keystore (as an SSL client-side key) in the event that the client keystore has multiple keys.
The UserDataConstraint annotation requires that the Web service be invoked using the HTTPS transport.
To configure transport-level Web services security via the UserDataConstraint annotation in your JWS file:
Configure SSL for the core WebLogic Server security subsystem.
You can configure one-way SSL 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.
To configure two-way or one-way SSL for the core WebLogic Server security subsystem, see Configuring SSL in Oracle Fusion Middleware Securing Oracle WebLogic Server.
In the JWS file that implements your Web service, add the @weblogic.jws.security.UserDataConstraint annotation to require that the Web service be invoked using the HTTPS transport.
For details, see weblogic.jws.security.UserDataConstraint in the Oracle Fusion Middleware WebLogic Web Services Reference for Oracle WebLogic Server.
Recompile and redeploy your Web service as part of the normal iterative development process.
See Developing WebLogic Web Services in Oracle Fusion Middleware Getting Started With JAX-RPC Web Services for Oracle WebLogic Server
Update the build.xml file that invokes the clientgen Ant task to use a static WSDL to generate the JAX-RPC stubs of the Web service, rather than the dynamic deployed WSDL of the service.
The reason clientgen cannot generate the stubs from the dynamic WSDL in this case is that when you specify the @UserDataConstraint annotation, all client applications are required to specify a truststore, including clientgen. However, there is currently no way for clientgen to specify a truststore, thus the Ant task must generate its client components from a static WSDL that describes the Web service in the same way as the dynamic WSDL.
When you run the client application that invokes the Web service, specify certain properties to indicate the SSL implementation that your application should use. In particular:
To specify the Certicom SSL implementation, use the following properties
-Djava.protocol.handler.pkgs=weblogic.net -Dweblogic.security.SSL.trustedCAKeyStore=trustStore
where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate).To disable host name verification, also specify the following property:
-Dweblogic.security.SSL.ignoreHostnameVerification=true
To specify Sun's SSL implementation, use the following properties:
-Djavax.net.ssl.trustStore=trustStore
where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate). To disable host name verification, also specify the following property:
-Dweblogic.wsee.client.ssl.stricthostchecking=false
See Configuring Two-Way SSL for a Client Application for details about two-way SSL.
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. You must also follow these requirements:
Create a client-side keystore that contains the client's private key and X.509 certificate pair.
The SSL package of J2SE requires that the password of the client's private key must be the same as the password of the client's keystore. For this reason, the client keystore can include only one private key and X.509 certificate pair.
Configure the core WebLogic Server's security subsystem, mapping the client's X.509 certificate in the client keystore to a user. See Configuring a User Name Mapper in Oracle Fusion Middleware Securing Oracle WebLogic Server.
Create a truststore which contains the certificates that the client trusts; the client application uses this truststore to validate the certificate it receives from WebLogic Server. Because of the J2SE password requirement described in the preceding bullet item, this truststore must be different from the keystore that contains the key pair that the client presents to the server.
You can use the Cert Gen utility or Sun Microsystem's keytool (http://java.sun.com/javase/6/docs/tooldocs/solaris/keytool.html) utility to perform this step. For development purposes, the keytool utility is the easiest way to get started.
See Obtaining Private Keys, Digital Certificates, and Trusted Certificate Authorities in Oracle Fusion Middleware Securing Oracle WebLogic Server.
When you run the client application that invokes the Web service, specify the following properties:
-Djavax.net.ssl.trustStore=trustStore
-Djavax.net.ssl.trustStorePassword=trustStorePassword
where trustStore specifies the name of the client-side truststore that contains the list of trusted certificates (one of which should be the server's certificate) and trustStorePassword specifies the truststore's password.
The preceding properties are in addition to the standard properties you must set to specify the client-side keystore:
-Djavax.net.ssl.keyStore=keyStore
-Djavax.net.ssl.keyStorePassword=keyStorePassword
Note:
All objects placed into Stub and MessageContext properties must be serializable and externalizable, and must have their implementations available on the server system CLASSPATH. This section describes the specific case of a custom SSLAdapter implementation.You can use a custom SSLAdapter implementation to provide client certificates and other services needed to establish SSL connections between client and server when using reliable messaging or buffering. The reliable messaging and buffering subsystems persist the state of a request over an SSL connection. In doing so, they persist the instance of the custom SSLAdapter used to establish the connection.
When the request is restored from persistence, the persistence facility must have access to the custom SSLAdapter class in order to properly restore the custom SSLAdapter object saved with the request. To allow for this, you must provide your custom SSLAdapter class via the server's system CLASSPATH (and not within an application deployed to the server).
The custom SSLAdapter must extend SSLAdapter, and is installed and enabled via the following procedure:
Create an instance of weblogic.wsee.connection.transport.https.HttpsTransportInfo.
Set the custom SSL adapter on that transport info by calling HttpsTransportInfo.setSSLAdapter(SSLAdapter adapter).
Set the transport info on the web services stub instance (stub of type javax.xml.rpc.Stub) by calling
stub._setProperty(weblogic.wsee.connection.soap.SoapClientConnection.TRANSPORT_INFO_PROPERTY,ti);
Where stub is the Web services stub, and ti is the HttpsTransportInfo you configured.
If you do not follow this procedure and provide the custom SSLAdapter class on the system CLASSPATH, a ClassNotFoundException exception is generated:
java.io.IOException: java.lang.ClassNotFoundException: examples.webservices.client.ServiceBase$TestSSLAdapter