Middleware Web Services

• Controlled XML schema and WSDL documents that define the structure of XML messages passed between client and service.
• Clear, concise, consistent structure of XML messages.
• XML message format that supports ease of use in common Java Web service integration toolchains, namely Apache Axis and JAXB.
• Develop an XML message format that is flexible enough to accommodate future growth while minimizing disruption to existing client applications. This turns out to be very difficult.

In summary we have attempted to build services that can be used by any Web service client integration language/platform/toolchain without preference for any one in particular without alienating common Java integration platforms.

The authoritative listing of available production Web services can be found at http://ejb.middleware.iad.vt.edu/jbossws/services.

The current XML schemata for all Middleware Web services are published and maintained at http://middleware.vt.edu/schema/. Integration with any service listed above requires passing SOAP messages conforming to the published schema at the endpoint addresses above. Careful study of the schemata is the first step to developing applications that rely on Middleware Web services.

Middleware Web services require SSL client authentication using an X.509 certificate issued by the Middleware CA in conformance with the ED Services policy where the CN of the certificate is the name of the ED-ID service for the requesting application.

All query services take a type of searchCriteria in the XML request payload. An example ED group query request follows:

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
 
<ns3:searchGroupsRequest 
    xmlns:ns3="http://middleware.vt.edu/schema/ed/query/" 
    xmlns:ns2="http://middleware.vt.edu/schema/ed/" 
    xmlns="http://middleware.vt.edu/schema/ed/manage/group/">
  <ns3:groupSearchCriteria>
    <ns3:firstResult>10</ns3:firstResult>
    <ns3:maxResults>10</ns3:maxResults>
    <ns3:administratorUupid>serac</ns3:administratorUupid>
  </ns3:groupSearchCriteria>
</ns3:searchGroupsRequest>
 
</soapenv:Body>
</soapenv:Envelope>

Note the presence of two elements that control the size and scope of results returned, maxResults and firstResult, respectively. By default, Middleware query Web services return 50 results unless a maxResults element is specified. The schema enforces reasonable limits on this value; consult the schema for the current limits.

The firstResult element is available to support result set pagination. If the client issues a query whose result set is of a size beyond the default or maximum allowed maxResults value, clients must retrieve subsequent results via pagination. In the above example, the query will fetch the next 10 elements beginning at the item whose index is 10 in the full result set. Note that result item numbering is 0-based, so the very first item in any result set is 0; in the example above, 10 indicates the 11th ordinal item.

Manager services are used to create and modify data, as well as perform other operations such that data policies are enforced. The format of messages passed to manager services follows the general outline below.

<ed:methodNameRequest>
  <ed:idparam>idvalue</ed:idparam>
  <ed:param1>value1</ed:param1>
  <ed:param2>value2</ed:param2>
</ed:methodNameRequest>

The ID parameter is most often the Registry sequence number of the entity being acted upon, in which case the identifying parameter will contain the string “uid” in its name. Group manager is a notable exception to this convention, where the identifying parameter is the group UUGID (Universally Unique Group Identifier), a string-based identifier that can be thought of as the group name. In every case element names have been chosen to describe their purpose in the context of the operation. The XML schemata describe the data types for all elements and, in particular cases, allowed values for a given request payload.

Every XML message that causes an error condition in the service is returned as a SOAP fault. Middleware Web services put errors in two broad categories:

1. Error condition caused by bad (user) input or illegal operations
2. System or application errors outside the control of the user or client application

An example of each type of message is provided below.

<?xml version='1.0' encoding='utf-8'?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<env:Fault>
<faultcode xmlns:codeNS="http://middleware.vt.edu/schema/ed/">
codeNS:Client.GroupStateException</faultcode>
<faultstring>Removal of the LAST administrator for a group is not
allowed -- blocking group is serac.test.fizzy</faultstring>
<faultactor>removePerson</faultactor>
</env:Fault>
</env:Body>
</env:Envelope>

Important aspects of the error messages aboves:

• The fault code has a well-defined format for most messages:

ns_prefix:[Client|Server].ExceptionClassName.

• The fault string is a human-readable error message that in some cases may be suitable for display to end users.
• The fault actor value is the name of the Java method inside the service that was invoked that caused the error condition.

Applications should inspect the structure of the SOAP fault code to determine what sort of error condition caused the error. In cases there the fault code contains the string “Client”, the Web service has determined that where is a high likelihood that the error was caused by bad (user) input or illegal operations emanating from the client. In those cases it is very likely the text of the fault string will be meaningful to a human user of the application, and may safely be directly displayed to them without additional information or context.

In cases where the fault code contains the string “Server”, the Web service has determined that the cause of the error is most likely outside the control of the client application, and almost certainly out of control of end users. In those cases the text of the fault string will almost certainly lack information and context needed for end users to comprehend and take action. Displaying the error message to end users in those cases is therefore not advised.

Middleware Web service authentication is performed via client X.509 certificates, where the client application must present a valid certificate issued by the VT Middleware CA in response to a client certificate request issued by the server. For Java applications, it is common practice to load a single keystore into the JVM containing credentials used by all applications running in the JVM. There may be situations, however, that are not well served by this configuration; for example, two applications running in the same container that must access the same Web service as different principals. We will present solutions for two common Java Web service client integration technologies, Apache Axis and Spring Web Services.

Carl Harris has provided us with a solution for Axis clients. His solution allows configuring credentials on a per-application basis by extending the Axis SimpleProvider class. We believe his solution is simple and well-documented enough that any clients needing such advanced configuration should be able to use, adapt, or extend his work without further guidance.

EdIdClientConfiguration.java compressed source

The strategy in Spring is centered on using a CommonsHttpMessageSender class that has an underlying HttpClient class customized according to instructions at http://hc.apache.org/httpclient-3.x/sslguide.html. In particular, we use the AuthSSLProtocolSocketFactory class to allow configuration of X.509 certificate credentials from the application classpath. For reference, a complete working solution can be found in Subversion at https://projects.iad.vt.edu:8443/svn/myvt/group-manager/branches/app-supplied-credentials, but some code highlights of the solution are mentioned below. Some important notes about our sample solution:

• The sample application contains a custom-built commons-httpclient JAR containing the contrib classes, which includes the AuthSSLProtocolSocketFactory. You may use this jar, or build your own from the HTTP Components 3.x source. We had to modify the build to get the contrib source compiled, and it was simpler to build a monolithic jar instead of a separate commons-httpclient-contrib.jar containing only contrib classes.
• The keystore and truststore are required to be in JKS format. This is different from most other Middleware client auth setups requiring Bouncy Castle key/truststores (BKS). The upshot is that you need a 1.5 JDK or later to handle the large modulus keys required by the Middleware CA. Alternatively, you could modify the AuthSSLProtocolSocketFactory source to use BKS format. The keystore format would ideally be a configuration parameter. HTTP Components project maintainers would likely welcome a patch for this.

Spring Configuration

...
  <bean id="socketFactory"
    class="org.apache.commons.httpclient.contrib.ssl.AuthSSLProtocolSocketFactory">
    <constructor-arg value="classpath:/edid.keystore" />
    <constructor-arg value="changeit" />
    <constructor-arg value="classpath:/edid.truststore" />
    <constructor-arg value="changeit" />
  </bean>
 
  <bean id="messageSender"
    class="edu.vt.middleware.groupmgr.ClientAuthSSLCommonsHttpMessageSender"
    p:protocolSocketFactory-ref="socketFactory"
  />
...

ClientAuthSSLCommonsHttpMessageSender.java

package edu.vt.middleware.groupmgr;
 
import org.apache.commons.httpclient.contrib.ssl.AuthSSLProtocolSocketFactory;
import org.apache.commons.httpclient.protocol.Protocol;
import org.apache.commons.httpclient.protocol.ProtocolSocketFactory;
import org.springframework.util.Assert;
import org.springframework.ws.transport.http.CommonsHttpMessageSender;
 
/**
 * Extends the Spring CommonsHttpMessageSender by allowing
 * explicit configuration of a AuthSSLProtocolSocketFactory that
 * governs SSL connection behavior.
 *
 * @author Marvin S. Addison
 * @version $Revision: $
 *
 */
public class ClientAuthSSLCommonsHttpMessageSender
  extends CommonsHttpMessageSender
{
  /** Default client SSL port for Middleware Web services */
  public static final int DEFAULT_SSL_PORT = 9443;
 
  /** HTTPS scheme */
  public static final String HTTPS_SCHEME = "https";
 
  /** Protocol socket factory for SSL client auth */
  private ProtocolSocketFactory protocolSocketFactory;
 
  /**
   * @param factory The SSL protocol socket factory used by HttpClient to make
   * SSL connections.
   */
  public void setProtocolSocketFactory(
      AuthSSLProtocolSocketFactory factory)
  {
    this.protocolSocketFactory = factory;
  }
 
  /** {@inheritDoc} */
  @Override
  public void afterPropertiesSet() throws Exception
  {
    super.afterPropertiesSet();
    Assert.notNull(protocolSocketFactory,
        "The sslProtocolSocketFactory property cannot be null.");
 
    Protocol.registerProtocol(HTTPS_SCHEME,
        new Protocol(HTTPS_SCHEME, protocolSocketFactory, DEFAULT_SSL_PORT));
  }  
}

Person query operations that return DSML have been removed in favor of the new searchPeople operation. The removed operations include the following:

• searchPerson
• searchPersonAttribute
• searchPersonByUupid
• searchPersonAttributeByUupid

• Updated addAlias operation request parameters:
  • Old signature: addAlias(string uupid, string alias)
  • New signature: addAlias(long accountUid, string alias)
• Updated removeAlias operation request parameters:
  • Old signature: removeAlias(string uupid, string alias)
  • New signature: removeAlias(long accountUid, string alias)
• Updated addForward operation request parameters:
  • Old signature: addForward(string uupid, string alias)
  • New signature: addForward(long accountUid, string alias)
• Updated removeForward operation request parameters:
  • Old signature: removeForward(string uupid, string alias)
  • New signature: removeForward(long accountUid, string alias)
• Updated setPreferredAddress operation request parameters:
  • Old signature: setPreferredAddress(string uupid, string alias)
  • New signature: setPreferredAddress(long accountUid, string alias)
• Updated setJmmStatus operation request parameters:
  • Old signature: setJmmStatus(string uupid, boolean status)
  • New signature: setJmmStatus(long accountUid, boolean status)
• Added addAccount operation for provisioning new email accounts.
• Added new operations for email account password management:
  • preValidatePassword - for password validation prior to email account creation
  • validatePassword - for password validation in support of password changes after account is created
  • setPassword - sets the email account password without any validation
  • changePassword - sets the email account password using the current password for verification

This service has been deleted and the operations it provided have been moved to PidManager and EmailManager services.

Renamed checkPassword operation to preValidatePassword.

Added new operations for user account password management:

• validatePassword - for password validation in support of password changes after account is created
• setPassword - sets the user account password without any validation
• changePassword - sets the user account password using the current password for verification

Spring Development Resources

Spring Framework Reference Documentation
The definitive resource on the Spring Framework. Lends itself to a chapter-wise read, or topic-by-topic reference as needed.

Spring API Documentation
An excellent day-to-day reference for Spring development. Browse or search the API (using site: operator in Google) for classes and method signatures. The JavaDoc class comments are generally excellent and frequently document usage patterns in addition to interfaces and behavior.

Spring Framework Forums
Search or post on the forums when Google search results are lacking.