Package examples.security.cert

This package demonstrates taking a digital certificate presented by a client during mutual authentication and returning an authenticated WebLogic Server User.

See:
Description

Class Summary

SimpleCertAuthenticator

A very simple certificate authentication example.

Package examples.security.cert Description

This package demonstrates taking a digital certificate presented by a client during mutual authentication and returning an authenticated WebLogic Server User. The code example is based on the SimpleCertAuthenticator.java class which implements the weblogic.security.acl.CertAuthenticator interface.

The SimpleCertAuthenticator class maps the e-mail name (the portion preceding the @ symbol) in the digital certificate for the client to a User in a WebLogic Server security realm. The SimpleCertAuthenticator class calls the realm.getUser() method to look up the e-mail name in the security realm in WebLogic Server. Other implementations of the CertAuthenticator interface could map a digital certificate to a User by looking up the holder of the digital certificate in a LDAP directory or in a RDBMS database.

Perform the following steps in order to build and run the examples:

1. Build the example
2. Configure the server
3. Run the example

Build the Example

1. Set up your development shell as described in Setting up your environment.

2. Compile the example by executing an ant build script or a command.
   • An ant build script is available in the samples/examples/security/cert directory. Enter the following command to execute the build script:

     ant

   • Enter the following command to compile the example:

      javac -d %SERVER_CLASSES% SimpleCertAuthenticator.java

3. Copy the demonstration digital certificate and private key for WebLogic Server and the digital certificate for the certificate authority from the \wlserver6.1\config\examples directory to the directory in which you are running the cert code example.
   • The name of the digital certificate is democert.pem.
   • The name of the digital certificate for the certificate authority is ca.pem.
   • The name of the private key file is demokey.pem.

   When using mutual authentication with a Java client, you can use the demonstration digital certificate and private key for both the client and the server.

   You can also use digital certificate and private key you obtain with the cert code example. Copy the digital certificates and the private key file into the directory in which you are running the cert code example.

Configure the Server

1. Bring up the Administration Console in a browser.

2. Click to expand the Servers node in the left pane of the Administration Console.

3. Select the exampleServer node in the left pane of the Administration Console.

4. Verify the SSL protocol is enabled.
   1. On the SSL tab in the Server Configuration window for the examplesServer verify that the Enabled checkbox is checked.
   2. Enter 7002 in the Listen Port field.

5. Define the following information about the digital certificate and private key for examplesServer on the SSL tab in the Server Configuration window:
   1. In the Server Key File Name field, enter the full directory location and name of the private key file for examplesServer (for example, ./config/examples/demokey.pem).
   2. In the Server Certificate File Name field, enter the full directory location and name of the digital certificate for examplesServer (for example, ./config/examples/democert.pem).
   3. Check the Client Certificate Enforced checkbox to enable two-way SSL.
   4. In the Trusted CA File Name field, enter the full directory location and name of the digital certificate for the certificate authority trusted by examplesServer (for example, ./config/examples/ca.pem).
   5. If you are using a PKCS-8 password protected private key, check the Key Encrypted checkbox. The demonstration private key is not password protected.
   6. Enter examples.security.cert.SimpleCertAuthenticator in the CertAuthenticator field.

6. If not already defined, define support as a User in the WebLogic Server security realm:
   1. Click to expand the Security node in the left pane of the Administration Console.
   2. Select the Users node.
   3. Add the User support with the password anything.

   Note: The Examples WebLogic Server comes pre-configured with users and groups; the preceding procedure is provided mostly for informational purposes.

7. Create an ACL that grants permission for User support to an existing resource in WebLogic Server.
   1. Select the Access Control Lists node in the left pane.
   2. Create a new ACL.
   3. In the Grant to User field, enter support.
   4. Click Save to Your Changes to Realm Implementation.
   5. Click Yes.

Run the Example

Note: The ACL example must be built before running the cert example.

1. Restart WebLogic Server.

   If you are using a PKCS-8 password protected private key, add the following command line option when starting WebLogic Server:

    -Dweblogic.management.pkpassword=password

   password specifies the password used to protect the private key.

2. Connect to WebLogic Server using mutual authentication.
   1. From a web brower, request an HTTPS connection to the resource you protected with an ACL. When using a web browser, users install their digital certificates in the web browser. If you use the demonstration certificate, you cannot use a web browser to test the CertAuthenticator class.

      If you use an HTTP port to connect from a web browser to a protected resource in WebLogic Server, the web browser should request a username and password. However, when you connect using the HTTPS port, SimpleCertAuthenticator establishes your identity without your having to log in.

   2. From a Java client, specify the following properties on a JNDI environment object:
      • In the INITIAL_CONTEXT_FACTORY property, enter weblogic.jndi.WLInitialContextFactory.

      • In the Context.PROVIDER_URL property, specify the T3S protocol and the host and port of the WebLogic Server to which you want to connect.

        For example, t3s://localhost:7002.

      • In the Context.SECURITY_AUTHENTICATION property, specify Strong.

        Use an InputStream array in the Context.SECURITY_CREDENTIALS property to pass the name of the files for the digital certificate file and private key file for the client.

   Enter the following command to run AltClient.java in the security.acl with mutual authentication:

    $  java -Dweblogic.security.SSL.ignoreHostnameVerification=true examples.security.acl.AltClient t3s://localhost:7002 -user joeuser
            -sslCert demokey.pem;democert.pem

   If you are using the demonstration digital certificates supplied with WebLogic Server, you must specify the IgnoreHostNameVerifier argument to over ride the default HostNameVerifier.

There's More...

Read more about mutual authentication and security in Programming WebLogic Security and Managing Security.