In the Java Web Server, security is based on the concept of realms. A realm defines protected resources on the server, users authorized to access the protected resources, and the mechanism (if any) by which those users will be authenticated. The Java Web Server provides several security realms. The certificateRealm, available only under the Secure Web Service, authenticates clients (users) through the use of client certificates--referred to as client authentication.

This document discusses the basic steps required to set up client authentication between a client and the Java Web Server. Some of those steps are performed on the client side, some are performed on the server side, as indicated below:

1. (Client) Requesting and importing a client certificate into the web browser
2. (Client) Retrieving and transmitting the client certificate to the Java Web Serve
3. (Server) Placing the client certificate in the Java Web Server
4. (Server) Enabling client authentication in the Java Web Server
5. (Client) Requesting resources protected by the certificateRealm

1. (Client) Requesting and importing a client certificate

If your browser supports client authentication, it will provide a mechanism by which you can request a client certificate--typically, this mechanism is a form.

1. Complete a certificate request following your browser's instructions. The browser will create a private key (data) and a public key (data) pair.
2. Submit the request. The private key will be stored in the browser. The public key will be sent to the certificate signing authority, along with identifying information from your certificate request.
3. Install the public certificate the certificate issuing authority will generate based on the public key you provided. (Follow the instructions provided with your browser for installing the public certificate.) It is this public certificate the browser will present when requested for client authentication by the server.

Note that certificate requests and the resulting certificate are specific to the type of browser from which the request was generated. For instance, the certificate generated by a Netscape Navigator certificate request form cannot be used in an Internet Explorer browser.

2. (Client) Retrieving and transmitting the client certificate

The Java Web Server needs the public copy of the client's public certificate, which it will store and use to validate requests received under that client's username.

1. The client should forward a copy of the public certificate received from the certificate signing authority to the Java Web Server administrator.

   Because the public certificate can be hard to extract from some browsers, clients may find it easier to provide the username under which they requested their client certificate and the name of their certificate issuing authority to the Java Web Server administrator.

   The administrator can then search the certificate issuing authority's website using the username as the search string. This search should find a copy of the public version of the client certificate. Click on download and save it to a known location, possibly under the admin/ directory of the Java Web Server.

Note that the certificate must be in X.509 format. If it is in some other format, you will need to use some utility (such as SSLeay) to convert it to the X.509 format before proceeding to the next step.

3. (Server) Placing the client certificate in the Java Web Server

The Java Web Server must store a copy of the client's public certificate. It is this certificate that will be used to authenticate submissions appearing to be sent by that user.

1. Place the client certificate into the Java Web Server. The procedure for doing this is the same as the the general procedure for adding a user to a realm--in this case, the certificateRealm.

   For instructions on completing the User screen, see the Administration Tool: Users online document.

1. Log into the Administration Tool
2. Select the Secure Web Service, then click the Manage button.
3. On the resulting panel, click the Security button then select Users.
4. On the Users panel, fill in the username. In the certificate field, simply type in the URL for the client certificate. (This can be http protocol for a remote location or the file protocol for a local location.)

4. (Server) Enabling client authentication in the Java Web Server.

Once a copy of the client's certificate is stored in the Java Web Server, the server must be told to use it for client authentication.

1. Activate client authentication in the Java Web Server. This is an option available through the Administration Tool.

   For a description of the screen where client authentication can be enabled, see the Administration Tool: Site Setup online document.

5. (Client) Requesting resources protected by the certificateRealm.

We mentioned at the beginning of this document that the resources being discussed are protected by Secure Sockets Layer (SSL) with HTTP -- this combination is referred to as the HTTPS protocol.

1. Having completed the forgoing steps, the user can request any of the protected resources using an URL of the following form:
    
   https://hostname:port/relative path to resource
    
   For example:
    
   https://www.sun.com:443/docs/membersonly.html

The request triggers the following chain of actions: the server responds to the client's request by requesting the client's certificate from the browser; the browser sends the requested certificate; the server compares the proffered certificate against the copy it has stored; if the two certificates match, access to the resource is granted -- if not, access is denied.

Top java-server-feedback@java.sun.com

Copyright © 1999 Sun Microsystems, Inc. All Rights Reserved.