Home
TOC Index |
Security for JAX-RPC
In this section, you'll learn how to create JAX-RPC service applications that use HTTP/SSL for basic or mutual authentication. If the topic of authentication is new to you, please refer to the chapter Web Application Security.
Note: The instructions in this section apply only to version 1.4 of the J2SE SDK.
There are certain steps you take to configure a JAX-RPC Web service endpoint for HTTP/S basic and mutual authentication:
- Use
keytool
, which is part of the J2SE SDK, to generate certificates and keystores.- Add an SSL Connector to Tomcat by running
admintool
, which is part of the Java WSDP.- Restart Tomcat.
- Add security elements to the
web.xml
deployment descriptor.- Set some properties in the client code.
- Build and run the Web service.
Detailed instructions for these steps follow.
Basic Authentication Over SSL
The steps for configuring a Web service for basic authentication over HTTP/S are outlined here. Refer to the section Mutual Authentication Over SSL for the steps for configuring the same service with mutual authentication.
Generating SSL Certificates for Basic Authentication
You use
keytool
to generate SSL certificates and export them to the appropriate server and client keystores. Keep in mind that the server and client keystores are created in the directory from which you runkeytool
.
- Go to the
<JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/security
directory.- Run
keytool
to generate the server keystore with a default password ofchangeit
.
- UNIX:
- Specify the server name, such as
localhost
, and user identity information as arguments tokeytool
. Enter the following:$JAVA_HOME/bin/keytool -genkey -alias tomcat-server -dname "CN=<server name>, OU=<organizational unit>, O=<organization>, L=<locality>, S=<state>, C=<country code>", -keyalg RSA - keypass changeit -storepass changeit -keystore server.keystore- Windows:
- The
keytool
utility prompts you to enter the server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response tothe
first prompt, which asks for first and last names. Enter the following:%JAVA_HOME%\bin\keytool -genkey -alias tomcat-server -keyalg RSA -keypass changeit -storepass changeit -keystore server.keystore- Export the generated server certificate.
- The
keytool
command is the same for UNIX and Windows. On UNIX, enter the following:$JAVA_HOME/bin/keytool -export -alias tomcat-server -storepass changeit -file server.cer -keystore server.keystore- Generate the client keystore.
- UNIX:
$JAVA_HOME/bin/keytool -genkey -alias tomcat-client -dname "CN=<client name>, OU=<organizational unit>, O=<organization>, L=<locality>, S=<state>, C=<country code>", -keyalg RSA - keypass changeit -storepass changeit -keystore client.keystore- Windows:
- The
keytool
utility prompts you to enter the client's server name, organizational unit, organization, locality, state, and country code. Note that you must enter the server name in response to the first prompt, which asks for first and last names. Enter the following:%JAVA_HOME%\bin\keytool -genkey -alias tomcat-client -keyalg RSA -keypass changeit -storepass changeit -keystore client.keystore- Import the server certificate into the client's keystore.
- For basic authentication, it is only necessary to import the server certificate into the client keystore. The
keytool
command is the same for UNIX and Windows. On UNIX, enter the following:$JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat- server -file server.cer -keystore client.keystore -keypass changeit -storepass changeitAdding an SSL Connector to Tomcat
In this section you will add the SSL Connector by running
admintool
, a utility that is included with the Java WSDP. For more information on the tool, see the appendix, Tomcat Administration Tool
- Follow the instructions in Adding an SSL Connector in admintool. In the right pane displayed by
admintool
, enter the values shown in Table 9-3.
Table 9-3 SSL Connector Values for admintool Field
Value
Type
HTTPS
Port
8443
Keystore
Name
< JWSDP_HOME
>/docs/tutorial/examples/jaxrpc/security/server.keystore
Keystore
Password
changeit
- Restart Tomcat.
- Make sure that the SSL Connector has been added by following the instructions in Verifying SSL Support.
Adding Security Elements to web.xml
The files for this example are in the
<JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/security
directory. For authentication over SSL, theweb.xml
file includes the<security-constraint>
and <login-config
> elements:<security-constraint> <web-resource-collection> <web-resource-name>SecureHello</web-resource-name> <url-pattern>/security</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>manager</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> </login-config>Note that the <r
ole-name
> element specifiesmanager
, a role that has already been specified in the<
JWSDP_HOME
>/conf/tomcat-users.xml
file. To learn how to update thetomcat-users.xml
file withadmintool
, see Managing Roles.Setting Security Properties in the Client Code
The source code for the client is in the
HelloClient.java
file of the<JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/security
directory. For basic authentication over SSL, the client code must set several security-related properties.trustStore Property
The value of the
trustStore
property is the fully qualified name of theclient.keystore file
:<JWSDP_HOME
>/docs/tutorial/examples/jaxrpc/security/client.key storeIn a preceding section, Generating SSL Certificates for Basic Authentication, you created the
client.keystore
file by running thekeytool
utility. The client specifies thetrustStore
property as follows:System.setProperty("javax.net.ssl.trustStore", trustStore);trustStorePassword Property
The
trustStorePassword
property is the password of the J2SE SDK keystore. In a previous section, you specified the default value of this password (changeit
) when runningkeytool
. The client sets thetrustStorePassword
property in the following line:System.setProperty("javax.net.ssl.trustStorePassword", trustStorePassword);Username and Password Properties
The username and password values correspond to the
manager
role, which is specified in the<
JWSDP_HOME
>/conf/tomcat-users.xml
file. (See Managing Roles and Users.) The installer utility of the Java WSDP automatically added the username and password values to thetomcat-users.xml
file.The client sets the username and password properties as follows:
stub._setProperty(javax.xml.rpc.Stub.USERNAME_PROPERTY, username); stub._setProperty(javax.xml.rpc.Stub.PASSWORD_PROPERTY, password);Building and Running the Example for Basic Authentication Over SSL
- If you haven't already done so, follow the instructions in Setting Up.
- Follow the instructions in Generating SSL Certificates for Basic Authentication and in Adding an SSL Connector to Tomcat. Don't forget to restart Tomcat.
- Go to the
<JWSDP_HOME>
/docs/tutorial/examples/jaxrpc/security
directory.- Type the following commands:
ant build ant deploy ant build-static ant run-securityThe client should display the following line:
Hello Duke (secure)Mutual Authentication Over SSL
To configure and create a JAX-RPC service with mutual authentication, follow all of the steps in the preceding section (Basic Authentication Over SSL) up to and including the command
ant
build-static
. Then, follow these steps:
- Export the generated client certificate.
- The
keytool
command is the same for UNIX and Windows. On UNIX, enter the following:$JAVA_HOME/bin/keytool -export -alias tomcat-client -storepass changeit -file client.cer -keystore client.keystore- Import the client certificate into the server's keystore.
- The
keytool
command is the same for UNIX and Windows. On UNIX, enter the following:$JAVA_HOME/bin/keytool -import -v -trustcacerts -alias tomcat- client -file client.cer -keystore server.keystore -keypass changeit -storepass changeit- Run the application:
ant run-securityThe client should display the following line:
Hello Duke (secure)Acknowledgement: This section includes material from the "Web Services Security Configuration" white paper, written by Rahul Sharma and Beth Stearns.
Home
TOC Index |
This tutorial contains information on the 1.0 version of the Java Web Services Developer Pack.
All of the material in The Java Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.