43 Using a Certificate Callback Handler to Validate End User Certificates

Oracle WebLogic Server provides a means to examine details about information (such as the end user's certificate, Subject, and IP address) passed by an end user issuing a request to determine whether authentication should succeed or fail. This capability is provided by the weblogic.security.SSL.CertificateCallback interface, which you can implement to create a certificate callback handler.

When configured with WebLogic Server, this callback handler is invoked automatically whenever a client request is received over a secure RMI connection; for example, one that uses the T3s or IIOPS protocols. To configure a certificate callback handler so that it is in effect for all secure inbound RMI connections, you define it as a WebLogic Server system property that is passed in the server startup command.

This chapter includes the following topics:

How End User Certificate Callback Handlers Work

When a client makes a secure RMI connection to a WebLogic Server instance that is configured with a certificate callback handler, WebLogic Server invokes the callback handler. The callback evaluates details about the end user that are contained in the connection request, then returns a boolean value indicating whether authentication is successful.

The CertificateCallback interface calls the validate method on an CertificateCallbackInfo instance, which contains methods to obtain the following information from the end user that is contained in the RMI connection request:

  • Client host name, IP address, and port

  • Client domain name

  • Destination host name, IP address, and port

  • Authenticated Subject

  • Client certificate

The callback implementation includes the logic that evaluates the client data that is obtained and returns true or false as follows:

  • If the callback returns true, authentication succeeds and the client connection to WebLogic Server is made.

  • If the callback returns false, a RemoteException is thrown containing the "Authentication denied" message.

Note:

If you use a certificate callback implementation in WebLogic Server, a callback is generated whenever a request is received over a secure port. As a result, using certificate callbacks may impose a performance overhead that should be taken into consideration.

Creating a Certificate Callback Implementation

The weblogic.security.SSL.CertificateCallback interface contains a single invocation on the validate method on a weblogic.security.SSL.CertificateCallbackInfo instance. The CertificateCallbackInfo instance contains methods to obtain details about the end user that are passed over the secure RMI connection.

You implement logic that evaluates the data that is returned and returns a true or false. The logic does not need to evaluate all data that is returned. Typically, only the certificate is evaluated; for example, obtaining the common name (cn) or distinguished name (dn).

See the following Javadoc in Java API Reference for Oracle WebLogic Server:

Configuring the Certificate Callback with WebLogic Server

To configure the callback with WebLogic Server, specify the callback implementation as a system property in the WebLogic Server start command. The property should point to the callback implementation class that is on the server's classpath.

For example, if the callback implementation class is MyCertificateCallback.java in the package com.mycompany.security, and MyCertificateCallback.class is in the server's classpath, the following command sets the callback implementation property in WebLogic Server:

java weblogic.Server -Dweblogic.security.SSL.CertificateCallback=com.mycompany.security.MyCertificateCallback

Note that if WebLogic Server is configured for one-way SSL, a client certificate is never sent to the server. Oracle recommends using certificate callbacks handlers only when WebLogic Server is configured for two-way SSL. See Configure two-way SSL in Oracle WebLogic Server Administration Console Online Help.