Some of the best software libraries I’ve used address both ends of the spectrum. There’s a common adage in software development (and I’m sure it goes back farther than that): “make the common things easy, and the hard things possible”. First, you don’t want to make things any harder than necessary for the majority of users that are just using the basic functionality of a library. If they don’t care about customizing and tweaking every little aspect of it, then the way they interact with the library should be relatively simple and straightforward. But for those users that have unique needs, the library should allow them to configure it in such a way to accommodate that. It is certainly my goal to address both extremes in the Shibboleth OpenID library, but it will happen in phases.

The first phase will address the edge-cases, those users of the library that tend to have unique needs and requirements. That may seem backwards, but I assure you it isn’t. First of all, the really practical reason for starting here is that Shibboleth is itself an edge case. The reason I chose not to use the existing Java OpenID libraries in the first place was that they didn’t adequately conform to the way Shibboleth needed them to work. But from a design perspective, I’ve found that this approach tends to yield better results anyway.

Small Pieces Loosely Coupled

I’ve learned that in order to make a system really flexible and modular, it’s best to architect it that way from the very beginning. You have to decide where the logical divisions of labor are within the system, and then translate that into the code itself. Each component should be relatively self-contained, it’s purpose should be clear, and its interface (the way it interacts with other components) should be separated from its actual implementation. Sometimes these components are obvious, and there are clear places where the code should be divided. But more often than not, its a judgement call. Architecture is often harder than actual construction, whether you’re talking about software or brick and mortar. It requires a lot of creativity because you’re often working from a blank canvas, but it also requires that your plans are grounded in what is actually possible. Architectural plans are worthless if they can’t actually be implemented in the real world in a practical way. By no means do I think that I’ve found the best architecture for this library, because it’s always subjective. Fortunately, I’ve had similar libraries that I’ve borrowed from heavily for inspiration, as well as much smarter developers that I work with to bounce ideas off of.

At its core, this library is an OpenID messaging library. It is capable of converting between generic HTTP messages and strongly typed OpenID objects that developers can work with. My last two posts have talked about this in detail. The library also provides the additional logic for implementing the OpenID specification, things like Diffie Hellman key exchange and OpenID message signing. What the library does not do is tell you how you must compose these pieces into a working system. That’s because there isn’t just one way to do it. It greatly depends on the application that is wanting to add OpenID support. If you’re using a Java framework like Tapestry or JSF, perhaps you have other processing that happens to the message before the OpenID library gets involved. How does the user get authenticated and where do the user attributes come from? I have no idea… that’s up to your application to decide. At this level, the library makes no assumptions (or at least as few as possible) about how all of these small pieces should be coupled together.

If this sounds like a lot of work left up to the user just for something as simple as OpenID, you’re right… it is a lot of work. But when you really need that level of control, it’s important that the library support that.

Addressing the Common Case

So what about everyone else, all the “mere mortals” who don’t need that much control, and just want to add OpenID support to some application using the default configuration? At a high level, I’d love to have a Servlet Filter that you can drop in front of your application, configure a few small things, and have it just work as an OpenID relying party. I’ve always been a huge fan of the Tapestry framework, so I’d love to have a Tapestry component that can be dropped in just as easily. All of these things are possible by building a layer that sits on top of those individual components in the library, and arranges them in a prescribed way.

Now, I don’t anticipate that a drop-in Servlet Filter will ever be a part of the core library, because I don’t think it belongs there. It would be a separate deliverable unto itself that simply relies on the library to do all of OpenID work. This also means that the Filter wouldn’t necessarily need to come from me, anyone could write it and make it available. I don’t imagine that the core library itself will ever have everything that the “common case” users will need. And I’m okay with that, because I’m not building an OpenID product, I’m building an OpenID library.

Current Status

This is by no means a complete picture of the Shibboleth OpenID library, but it should give you a rough idea. It identifies some of the larger components of the libraries, and some of the interdependencies.

The orange blocks are pieces that are basically complete and present in the current library. All of the message handling is complete for OpenID 2.0 message, as well as three of the most popular message extensions (SReg, AX, and PAPE). Additionally, association management is done, and a very simple AssociationStore is provided (though it needs a little improvement). The security layer is complete insofar as signing and verifying signed messages. The yellow blocks represent pieces that are not yet complete, but will be included in the core library in the future. The discovery component is still up in the air a little bit because it’s not completely clear if we’ll be using XRD, XRDS, or both. The portions of the security layer that depend on discovery are, of course, waiting on the completion of the discovery stack. Those pieces include everything that an application would need to construct an OpenID provider or relying party. They implement the full OpenID protocol.

But those components alone leave a lot to be filled in by the application using the library. It says nothing about how an incoming HttpServletRequest object is converted into an OpenID Message. The application would be responsible for instantiating the specific objects and wiring them together to actually get a working AssociationManager. And for applications that wish to have control over these specific aspects of an OpenID flow, this is a good thing. The next layer up on the stack however, the yellow “Managers” block, will provide simple Manager objects that wire things together in a prescribed way. Most users of the library will deal with the Manager layer, and probably nothing else. Only when they have specific needs will it be necessary to dig any deeper.

Now this last layer is actually nothing special… it’s a very common pattern, and both OpenID4Java and Joid work in very similar ways. I point it out only to note that while this layer will be part of the core library in a future release, it isn’t right now. Much of the code that will likely make up these components has already been written, but in the form of the Shibboleth IdP extension. For the last few months I’ve been simultaneously building both a generic OpenID library, as well as an actual product that makes use of the library. One of the tougher ongoing challenges while doing this is in deciding which of the two projects a particular bit of code goes into. Much of the time it’s clear, but when in doubt, I’ll put something into the Shibboleth extension rather than the library. If anything, I want to err on the side of keeping the library “pure” so to speak. To not accidentally bake any assumptions into the library itself that might limit its flexibility. One of my focuses after the holidays will be in identifying which pieces need to be refactored from the Shibboleth extension back into the core library in order to build out that management layer.

(And in case it’s not clear, the final layer in grey in the stack above are other pieces that will make use of the OpenID library, but will likely not be part of the library itself.)

Central Registry

As we mentioned, every OpenID message type has a number of supporting classes. Let’s take the authentication request message as an example. You have:

• AuthenticationRequest — interface that defines this specific OpenID message type
• AuthenticationRequestImpl — default implementation of this message type
• AuthenticationRequestBuilder — builder of AuthenticationRequest instances
• AuthenticationRequestMarshaller — converts AuthenticationRequest message into a ParameterMap
• AuthenticationRequestUnmarshaller — converts ParameterMap into an AuthenticationRequest message
• AuthenticationRequestValidator — this wasn’t talked about last time, but is responsible for validating that an AuthenticationRequest message contains all of the requisite parameters

All classes except for the actual message implementation must be thread-safe, as only a single instance is maintained by the library (technically they don’t follow a singleton pattern, but only one instance is typically used). All of these are stored in central registries, so that they can be retrieved to marshall or unmarshall a message as needed. Each one has it’s own factory that allows registering and looking up of specific implementations:

• MessageBuilderFactory
• MessageMarshallerFactory
• MessageUnmarshallerFactory
• MessageValidatorFactory (not yet implemented as of this writing)

MessageValidator implementations are registered based on the message class that it validates. For the other three factories, implementations are registered based on a QName which consists of the OpenID protocol namespace URI, and the value of the mode parameter. Yes, there are three OpenID message types that don’t actually have a ‘mode’ parameter, but I’ll save that discussion for another post. Also, the QName here doesn’t exactly represent a namespaced parameter name like it does in the ParameterMap, instead it is just a container for a namespace URI and a string value. Perhaps this is technically a misuse of the QName object, but it’s working fine for now. A static instance of each factory is available from the Configuration class.

Message Flow (redux)

So now let’s go through a message flow like we did last time, and look at how each of the factories are used. (At the time of this writing, I’m still working on hooking in the MessageValidators, so I won’t be talking much about that).

Remember that when a message comes in, it is in some kind of transport specific encoding. Depending on how the message was received and the format it is in, an appropriate MessageDecoder is used to convert it into a ParameterMap. The next step is to find an appropriate MessageUnmarshaller to convert this ParameterMap into an actual Message object. The MessageUnmarshallerFactory has a getUnmarshaller(ParameterMap) method that will lookup exactly what we need. Once we have an unmarshaller, we can call its unmarshall(ParameterMap). This method is responsible for building an appropriate Message object, and then populating it based on the data provided in the ParameterMap. Internally, the unmarshaller uses the MessageBuilderFactory to find an appropriate MessageBuilder using the getBuilder(ParameterMap) method. Once the correct builder is obtained, its buildObject() method is called to get an instance of the Message object. This instance is then populated using data from the ParameterMap and returned. (If anyone wants to volunteer a flow chart that illustrates this, I’d be greatly appreciative!)

When it comes time to send a message back out, the MessageMarshallerFactory’s getMarshaller(Message) method is called to get the correct MessageMarshaller for a given message. The marshaller’s marshall(Message) method is called and returns a ParameterMap, and that is passed through an appropriate MessageEncoder to send it out on the wire.

Custom Implementations

The library comes with default implementations for all of this, so a user can simply choose to ignore all of this plumbing and be just fine. But just in case you do want to customize part of this, how would you go about doing so? Simply by registering them with the appropriate factory. Let’s say you want to provide your own AssociationRequest implementation for whatever reason. But maybe you don’t necessarily care to customize the way the data is unmarshalled into and marshalled out of the object… the default implementations for those are fine. You would of course have your custom AssociationRequest:

public class MyAssociationRequest implements AssociationRequest {
    /* implementation here */
}

Then to make sure that your custom implementation is built instead of the default implementation provided by the library, you would also need to provide a MessageBuilder:

public class MyAssociationRequestBuilder implements 
             MessageBuilder<AssociationRequest> {

    public AssociationRequest buildObject() {
        /* build and return an instance of MyAssociationRequest */
    }
}

Then register your message builder:

MessageBuilder myBuilder = new MyAssociationRequestBuilder();
QName qname = new QName(OpenIDConstants.OPENID_20_NS, AssociationRequest.MODE);
Configuration.getMessageBuilders().registerBuilder(qname, myBuilder);

Once your builder is registered, it will be used to build AssociationRequest objects for all incoming messages of that type. However, the default marshaller and unmarshaller for that type will continue to be used… you don’t need to worry about that. And once I get the validators hooked in, that will just work as well with your custom class. Or, you could provide your own Validators if you like. You can customize as much or as little of the library as you want.

I don’t imagine that anyone will want to provide custom message implementations very often, but the option is most certainly there. What is far more likely is providing a custom message extension like Attribute Exchange or PAPE. That works in very much the same way, which I’ll explain next.

Let me first preface this by clarifying that I’m not saying the existing OpenID libraries are not usable. Quite the contrary, I know that the OpenID4Java library is used for AOL’s OpenID provider, on Google’s Blogger, as part of Sun’s OpenSSO, and countless other projects. Additionally, JOID powers Verisign’s very usable PIP. There is no question that they work for many use cases. However, they lack the clean architecture I was looking for, which can really only be corrected by starting from a blank canvas.

(I’m not sure how many posts this will take, or how sensical the order of things will be, but better to go ahead and get it written down in some form.)

Message Handling Flow

One of the most immediate differences you’ll see in the Internet2 library is the very clear separation of logic in the message handling code. I wanted the core message objects to be simple Java beans that provide access to strongly typed properties, and nothing more. When I’m processing an OpenID message, I don’t want to be thinking about how that message was encoded during transit. Additionally, I don’t want to duplicate code if at all possible, so there needs to be one very clear place where any particular process is implemented. To achieve this, messages are transformed into three distinct formats as they are being processed.

When a message comes in to an OpenID provider, it is in some kind of transport specific format. Typically that will be a URL-encoded string that is taken either from an HTTP POST request body, or from an HTTP GET request query string. Alternately, it may be a Map retrieved by calling ServletRequest.getParameterMap. This transport specific format needs to first be converted into some kind of common intermediary format so that the next step in the process can deal with all messages in the same way, regardless of transport method. In the Internet2 library, this common format is a ParameterMap.

ParameterMap

A ParameterMap is simply a LinkedHashMap with QName keys, String values, and a little additional logic. Why QNames for keys? Aren’t those for XML? Yes they are, but they actually work beautifully for OpenID message parameters as well. You see, an OpenID message is really just a collection of namespace qualified parameters, and can be quite easily represented in XML. (Yes, this is a little bit of a rabbit trail, but it’s interesting nonetheless). Let’s start with a really simple KVF encoded OpenID message:

openid.ns:http://specs.openid.net/auth/2.0
openid.mode:checkid_setup
openid.claimed_id:http://example.com/
openid.identity:http://example.com/
openid.ns.sreg:http://openid.net/extensions/sreg/1.1
openid.sreg.required:email,fullname

Yeah it has no signature, etc, but that’s not the point. What might this look like in XML?

<message xmlns="http://specs.openid.net/auth/2.0" 
         xmlns:sreg="http://openid.net/extensions/sreg/1.1">
    <mode>checkid_setup</mode>
    <claimed_id>http://example.com/</claimed_id>
    <identity>http://example.com/</identity>
    <sreg:required>email,fullname</sreg:required>
</message>

See how cleanly it maps? This is no accident. This is a very common pattern for handling namespace qualified parameters. First you assign your namespace to an alias, then you use that alias as a prefix for any parameters that are part of that namespace. The simple registration ‘required’ parameter name has three parts: there’s the base parameter name (“required”), the namespace alias (“sreg”), and the actual namespace URI which is declared separately (“http://openid.net/extensions/sreg/1.1”). A Java QName object consists of three parts: a namespace URI, a local part, and a namespace prefix. Slightly different terms, but exactly the same concepts.

Okay, so back to our OpenID library. We’ve taken our transport specific encoding, passed it through an appropriate MessageDecoder, and ended up with a ParameterMap. Before we move on, I want to point out one more thing about the parameters in a ParameterMap. None of the parameter names contain the “openid.” prefix. This prefix is specific to messages that are encoded using URL Form encoding, since that’s the only way to identify which parameters are part of the OpenID message. One of the jobs of the URLFormCodec is to strip this prefix as messages come in, and add the prefix as messages go out. The message encoder and decoder is the only part of the entire library that knows anything about this prefix, and quite frankly it’s the only part that should.

Okay, so now that we have our ParameterMap, it needs to be converted into an actual message object, which is the job for a MessageUnmarshaller.

Unmarshalling messages

Message unmarshallers are responsible for taking a ParameterMap and using it to populate a specific kind of message object. Remember the desire for message objects to have strongly typed properties? The corresponding unmarshaller for that message type is the one and only place that needs to worry with how the parameter passed on the wire gets converted into that strong type. For example, AssociationRequest messages may include the Diffie-Hellman public key of the OpenID relying party. Java provides a very specific object just for that called DHPublicKey, so that’s what we want our AssociationRequest object to use. Parameters can only be passed as strings during transit, so the AssociationRequestUnmarshaller (and nothing else) is responsible for knowing how to convert that string into a DHPublicKey.

Similarly, Attribute Exchange fetch requests may include a list of required attributes it wants for a user. These attributes are identified by URIs, so Attribute Exchange does it’s own aliasing similar to the namespace declarations we saw above. This way, the “ax.required” message parameter need only contain a comma-separated list of attribute aliases rather than the full namespace URIs. But when you get right down to it, these aliases are just an optimization that is used during transport. Really all that’s being represented is a list of attributes URIs. This is why the FetchRequest object in the Internet2 library exposes this particular message parameter simply as a List of attribute URIs. It’s the FetchRequestUnmarshaller that is responsible for taking the AX message parameters, dereferencing the attribute aliases, and populating the FetchRequest object appropriately.

Reversing the process

What about returning OpenID response messages? We just do the same process in reverse. The message object is passed through an appropriate MessageMarshaller which populates a ParameterMap. And the ParamerMap is in turn passed through a MessageEncoder that produces some kind of transport specific format. That may be a Key-Value form encoded string, as is the case with direct responses, it may be a URL suitable for redirecting the user to, or it may be an HTML response to use for HTML form submission.

Uniformity over brevity

Depending on how you separate them, there are roughly nine different message types in the core OpenID 2.0 spec, and for each of these message types, the Internet2 library has five files that handle the processing. There’s the message interface, the concrete implementation, the message builder (which I didn’t actually talk about in this post), the message marshaller, and the message unmarshaller. At times all these files may seem needlessly verbose, especially when you see that some of them are only a few lines long. It turns out that this separation doesn’t necessarily result in more lines of code, just that the code is broken up into smaller chunks. Besides, the goal here is not conciseness. The goal is uniformity and predictability in how messages are processed, as well as clean, logical separation of duties. When every message is processed in exactly the same way, bugs tend to expose themselves much earlier in the process, and strange edge cases are far rarer. When things are logically separated, it makes the overall architecture much easier to understand. And perhaps more importantly, it makes it possible to fully understand one part of the library without needing to be concerned with others. You can go in and look at the code for signing messages, and not have to wade through code dealing with transport encodings.

Never place jars that are necessary for Ant task definitions in your Java classpath (/System/Library/Java/Extensions, /Library/Java/Extensions/, ~/Library/Java/Extensions)

The problem is that Java tries to load these jars before it has loaded the Ant jars that they rely on. These jars that contain task definitions should either be placed in the Ant classpath ($ANT_HOME/lib, ~/.ant/lib) or in your project’s lib directory and referenced directly using the classpath attribute of the taskdef.

As the OSIDs gradually gain acceptance, I think some simple automation like this would really help people develop proper implementations.