IMPORTANT NOTE TO DEVELOPERS:

I have moved the project's source code to GitHub, and the rest of this site's content will follow -- in a while. Just know that there will be no more commits against the Google Code repository, so if you want to stay up-to-date about the project's progress, follow me on GitHub!

For an overview of what has changed in the latest builds, please go to ChangeLog.

What is Signpost?

Signpost is the easy and intuitive solution for signing HTTP messages on the Java platform in conformance with the OAuth Core 1.0a, Draft 3 standard. Signpost follows a modular design, allowing you to combine it with different HTTP messaging layers. Click here for a list of supported HTTP libraries.

Signpost is a community effort and may be downloaded, modified, and redistributed under the terms of the Apache License version 2.

Signpost is currently in beta stage, which means it may contain bugs.

Goals of Signpost

Signpost has been designed with several principal goals in mind:

Simplicity

Using Signpost is as simple as it could possibly get -- all actions are executed with only a few lines of code. For example, this is how you would sign a classic Java HTTP message using Signpost:

        // create an HTTP request to a protected resource
        URL url = new URL("http://api.example.com/protected")
        HttpURLConnection request = (HttpURLConnection) url.openConnection();

        // sign the request (consumer is a Signpost DefaultOAuthConsumer)
        consumer.sign(request);

        // send the request
        request.connect();

Signpost exposes a minimalistic API designed for two purposes: Signing HTTP messages and requesting tokens from an OAuth service provider. Everything else is beyond the scope of the OAuth specification, and is thus left to the HTTP messaging layer, where it belongs.

For more exhaustive examples, please refer to GettingStarted.

Unobtrusiveness

Signpost tries to be as unobtrusive as possible. Unlike other implementations, Signpost does not wrap the entire HTTP layer and hides its features from the client. Instead, you simply pass an HttpRequest object to it, and Signpost will sign the message using the credentials it was configured with.

This means that all the power and flexibility of the underlying HTTP engine is still at your fingertips!

Modularity

Since version 1.1, Signpost comes in modules. Apart from the core module, which you always need, you can download additional modules to support other HTTP messaging libraries than the one coming with the standard Java platform (which would be java.net.HttpURLConnection).

Apart from HttpURLConnection, Signpost currently has modules for Apache Commons HTTP version 4, and Jetty HTTP Client version 6.

Limitations

Simplicity doesn't come free. Thus, Signpost currently makes certain assumptions to reduce the complexity of both the implementation and the API.

Deviations from the OAuth standard

• Message signing using public key encryption (as per section 9.3) is currently unsupported. Message signing using the PLAINTEXT and HMAC-SHA1 methods is supported, however.
• The OAuth standard demands that OAuth request parameters may be put in the URI query string or in the message payload. Signpost will never do that; instead, all OAuth protocol parameters are written to the HTTP Authorization header field. Anything you put there will be overwritten by Signpost.
• Accounting for existing OAuth parameters in the Authorization header (as per sec. 5.4.1) is currently unsupported (i.e. anything in the Authorization header prior to message signing will not become part of the signature)
• Signpost currently does not support writing OAuth protocol params to the WWW-Authenticate header field

I believe that even with those restrictions in place, Signpost will work for the majority of its users. Trading in rarely used features for more simplicity and ease of use was a design decision. If that doesn't work for your setup, Signpost is probably not the best choice for you.

Thread Safety

Signpost is not thread safe and probably will never be. Signpost objects are very lightweight, so you are adviced to create an OAuthConsumer and OAuthProvider for every thread in your application that must send signed HTTP requests.

Google Android

Signpost works flawlessly in conjunction with Android, Google's software stack for mobile devices. In fact, Signpost has already signed thousands of HTTP requests at this very moment, as it is an integral part of Qype Radar, our geo-sensitive mobile application for Android that finds the best places near you.

OAuth Service Providers

In a perfect world, Signpost would work with every service provider implementing the OAuth standard correctly. Implementations however can be buggy, or people tend to interpret the standard in different ways, making OAuth clients incompatible with some OAuth service providers at times.

I don't know with how many of the existing OAuth service providers Signpost plays well. But to not leave you completely in the dark, here is a list of some Web services using OAuth which I tested to work with Signpost:

• Twitter (instructions, example code)
• YAHOO! Fire Eagle (example code)
• Google services (example code)
• Qype

Support and discussions

Please use the Signpost Google Group for questions, feedback and discussion.