I’ve talked with core team about this numerous times… in fact, I spoke at WordCamp Portland and Seattle these last two weeks and talked with Matt about it. For the most part, I actually agree with him that OpenID doesn’t necessarily belong in core, at least not yet.

There’s a lot of thought being given to how WordPress can serve as your “digital hub” on the web. Right now, Automattic is playing in that space in the form of BuddyPress. Now right now, BP allows you to create another social network silo. BP installations don’t talk to each other, and there’s no way to use your account on one BP network to login to a different BP network. I talked with Mark Jaquith this weekend about my desire to see this outward facing functionality. For that, I think OpenID becomes painfully obvious.

I would also like to see this OpenID plugin deployed on WordPress.com to replace the existing plugin. Currently, all WP.com blogs are OpenIDs, but you can’t login or leave comments using an external OpenID. And currently, almost no one uses the existing OpenID provider. Of course, I would argue that this is because they haven’t done a good job of promoting it or adding any new features like SReg or AX. Using my OpenID plugin would greatly enhance the OpenID provider functionality on WP.com, and it would allow people to use OpenID when leaving comments. Some of the changes that are included in 3.3 are actually steps toward cleaning up the plugin so that it is more suitable for deploying on WordPress.com. There’s still more work to be done on this front, but it’s something I intend to continue pursuing.

As for inclusion in WordPress core, I just don’t think we’re there yet. The OpenID plugin is pretty popular, but it is far from having the critical mass that would justify inclusion in core. I am a firm believer that WordPress should by no means try and include every cool feature under the sun in core. It would quickly grow out of control. I do believe, however, that the appropriate hooks should be provided in core to allow any cool feature under the sun to be added as a plugin. The core dev team agrees with me on this, and they’ve been very good about making whatever changes were necessary to allow plugins to provide that functionality. In fact, I overhauled how the authentication system is extended in WordPress 2.8 simply to make things like OpenID and OAuth much easier to implement.

A few other things I’d want to see fixed before considering inclusion in core… the OpenID plugin weighs in at what? almost 900K? Remove the screenshots and readme.txt and you’ve got 700K left. Over 500K of that is the JanRain OpenID library. So size is an issue. Also, the biggest problem that people have with getting the plugin to work is related to their environment. WordPress is known for having a very minimal set of requirements to get it running. I’d really want to track down and fix a lot of these weird environment issues that continue to plague the plugin. Finally, we need a really solid UI, both comment form integration and the admin side. I’m pretty happy with the new comment form integration, but the current admin screens need work. More than anything, there is just a lot of functionality in the plugin and it’s hard to boil it down. Especially when you consider both the OpenID consumer and provider options, both site-wide and per-user.

Second, this release features a new user interface for the integrating OpenID into the WordPress comment form. Instead of simply advertising OpenID support on the “Website” field, and always attempting OpenID authentication, the plugin now detects OpenID support for a URL, and gives the user the option to authenticate the comment. This provides a cleaner, less obtrusive interface that should work on most all themes. It also gives the user the option to not authentication that particular comment if they don’t want (particularly useful if you’re on a mobile device or in a hurry and don’t want to mess with OpenID). Feel free to try it out on this post if want. You really don’t even have to submit the comment to see it in action… just enter a valid OpenID URL for the website field, and move focus somewhere else (ie, click in the comment box like you’re going to type a comment). There is currently no option to revert to the old style of comment form integration, so hopefully folks will like this new UI. If you really don’t like it, you always have the option of turning off comment form integration and modifying your theme to your heart’s content.

Finally, this release includes a lot of minor bug fixes that people have been complaining about (sorry it took so long). I’m sure I didn’t get to all of them, so please let me know what I missed, and I’ll try to do more regular minor releases with these smaller fixes.

I’ll additionally note that working on WordPress plugins is no longer part of my day job, so I currently work on them rather sporadically as I have time. The changes in this release have been developed a few hours at a time over the last couple of months. I’ve been running trunk here on my site for quite some time and haven’t had problems, but you never know. Please use the DiSo issue tracker to report any new bugs, or to remind me of existing tickets that are still not fixed in this release.

The very same mechanisms that makes WordPress extensible can be used to make your plugin extensible as well. Most of the time this will mean action and filter hooks. As a plugin author, you are no doubt familiar with how these hooks work, since your plugin is using them to hook into WordPress. But what some newer developers may not realize is just how easy it is to provide your own hooks to extend the functionality of your plugin.

Where to add hooks

When you’re getting started with your plugin it may not be obvious where to add hooks, and that’s okay. If you already have a number of people using your plugin, then perhaps you may have already received requests from people wanting to add some kind of functionality to the plugin or change how something works. Oftentimes these changes are appropriate to add directly into your plugin, and you are most certainly encouraged to do so when it makes sense. But sometimes the request represents an edge-case… something that one individual is wanting to do, but is very likely not going to be useful to most people using your plugin. Even worse, making such a change may be confusing or even undesirable by other users. In these cases, see if you can provide the appropriate hooks to allow people to extend your plugin to suit their needs.

Extended Profile is a good example which provides quite a few hooks for people to extend. One of the core features of the plugin is that it allows you to output an hCard Profile on a page, like I have on the front page of willnorris.com. The plugin provides most of the common hCard attributes that we thought an individual might be interested in like name, website, address, telephone number, etc. To collect this data from the user, the plugin extends the standard WordPress Profile administration page. But we knew that users might already have a different plugin capable of providing this data, or that they may want to pull the data form some other source. Additionally, the hCard microformat supports a number of other attributes that we didn’t include in the plugin. In order to support these use-cases, we used a combination of action and filter hooks (mostly filters, in our case) to allow the hCard profile to be supplemented, or outright replaced. This is actually how I added the “Last Seen” geo data to my hCard, which pulls data from Brightkite.

As a general rule of thumb, action hooks are used to alert other plugins that you are at a particular point within a process. Perhaps that you’re about to begin doing something, or that you’ve just finished doing something which other code may care about. If you’re printing things to the screen, an action hook may be a good place to allow other plugins to print things as well at a very particular point in your plugin’s processing.

Filters are intended to allow other pieces of code to actually modify something that your plugin has done. As mentioned above, the Extended Profile plugin makes heavy use of filters to allow other plugins to modify various aspects of the generated hCard before it is printed to the screen. In fact, the plugin hooks into its own filters in order to provide most of the functionality, just like any other plugin would.

That last point is worth underscoring: hooks are not just for other plugins to use, you should be using them yourself. WordPress makes extensive use of its own actions and filters, just take a look at default-filters.php. This has a number of benefits — it allows you to keep your own code fairly clean and modular, but perhaps more importantly it allows other plugins to actually remove functionality they don’t want using the remove_action and remove_filter methods. When it comes to making your plugin extensible, being able to remove functionality is just as important as the ability to add it.

How to add hooks

Adding new action or filter hooks is deceptively simple — there is no registration of hooks, you simply call do_action or apply_filters as needed. A simplified version of what happens in the Extended Profile plugin might look like this:

function get_extended_profile($user_id) {
    // start output buffering
    ob_start();

    // call the action hook which actually builds the profile
    do_action('extended_profile', $user_id);

    // get buffered content
    $profile = '<div id="profile">' . ob_get_contents() . '</div>';
    ob_end_clean();

    // filter everything before returning
    return apply_filters('post_extended_profile', $profile, $user_id);
}

Here you can see both a custom action and filter being used, first to build the profile and then to filter it. When adding hooks to your plugin, its important to think about what data those hook functions may need in order to do something useful. For example, functions which hook into the ‘extended_profile’ action need to know the ID of the user the profile is being built for so that they can fetch the appropriate data. The same user ID is also passed to the ‘post_extended_profile’ filter for the same reason. With filters it’s important to remember that only the first parameter passed into the hooking functions gets filtered. You can certainly pass other data as well to provide context, but only the first one is filtered (which is actually the second parameter passed to apply_filters, since the first one is the filter name).

The real beauty of WordPress action and filter hooks is in how lightweight the entire system is. Calling a hook that has no registered functions returns almost immediately. And registering a function to a non-existent hook has basically no overhead, and absolutely no consequence… the function simply never gets executed. While you should certainly think through your plugin and add hooks at the logical points, don’t worry too much about adding too many. Consider this: on a standard, out of the box WordPress installation with no plugins activated, a page load can easily cause over 1,000 calls to do_action and apply_filter. Having your plugin add in a handful more is not going to have any kind of adverse effect on WordPress performance, and you will potentially make your plugin users much happier.

Custom Constants

Another way to expose additional functionality within your plugin is through the use of custom constants. This is generally most appropriate to enable advanced functionality that you don’t want to expose through the normal WordPress option pages. For example, suppose you have a plugin which makes API calls to some service. The URL for that API endpoint is constant, but you might want to allow it to be overridden for testing purposes. Use a PHP constant for your API URL, but check to see if it is already defined:

// near the beginning of your plugin
if ( !defined('MY_PLUGIN_API_URL') ) {
    define('MY_PLUGIN_API_URL', 'http://api.example.com/service'); // default value
}

// throughout the rest of your plugin, always use the constant
file_get_contents( MY_PLUGIN_API_URL . '?user=joe' );

In this way, the API URL can be overridden by defining the constant in wp-config.php:

define('MY_PLUGIN_API_URL', 'http://testing.example.net/test-service');

This is not as common as using action and filter hooks, but is still useful especially when you want to ensure that other plugins are not able to manipulate the value. Unless you do some additional checking, you never know what functions may be hooking into your filter or what they’re going to do with the value… in fact that’s kind of the point, you’re not supposed to know or care. But in cases where you want to allow the user to define a custom value, but also ensure that other plugins don’t manipulate the data in any way, constants are the way to go.

A final note if you do end up adding hooks or constants to your plugin. Because so many plugins aren’t able to be extended in these ways, it is well worth drawing attention to the fact in your plugin’s readme.txt. You can even go so far as to document all of the extension points as I did with the OpenID plugin, but you don’t necessarily have to. Just pointing out that hooks exist is often enough, developers can quickly scan your code for them.

echo '<script type="text/javascript">
    jQuery.get("' . plugins_url('my-plugin/ajax-handler.php') . '");
    // do something with AJAX data ...
</script>';

This is not a problem in and of itself, in fact it’s great that the plugin developer is actually using the plugins_url function! The problem arises in the my-plugin/ajax-handler.php file itself. If that plugin needs to make use of any WordPress data or functions, then the developer is certain to do something very ugly. You’ll know it when you see it:

require_once('../../../wp-load.php');

// or sometimes you'll see...
require_once('../../../wp-config.php');

So what is this, and why is it so bad? Well, the wp-load.php is a file provided by WordPress core that bootstraps the WordPress environment. It loads in the wp-config.php file, loads all the common WordPress functions and classes, initializes the database connection, and gets everything in place to process the request. These are all important things, and provides a lot of functionality that the plugin developer may need. The problem is that in the require_once call above, the plugin developer is assuming that the wp-load.php file is in a directory exactly three levels up in the filesystem from their plugin directory. In a standard WordPress deployment, this will be true and everything will work fine (for the most part). But as we’ve already seen, WordPress allows deployers to move where their wp-content or their plugins directory lives, so the above code will break completely. Yes, there are files in WordPress core that do something similar to the above, for example wp-admin/admin.php. But these are safe for WordPress core files because they do know where certain files will be. It is never safe to make this assumption from a plugin. I think it’s pretty safe to say that if you have a require or include call that goes up more than a couple of directories (“../../”), you’re almost certainly doing it wrong.

A couple of points to emphasize before moving on: if your plugin files are not accessing any built-in WordPress functions, classes, or data, calling them directly should be just fine. Also, if you’re doing AJAX calls on admin pages, use the built-in functionality WordPress core provides.

The Right Way

So the right way of doing this is actually pretty straightforward conceptually, but in practice there are a couple of ways to do it depending on your needs. The short answer is that instead of calling your plugin file directly, you must send the request through the standard WordPress request handling mechanisms. This requires two things: constructing your request properly, and then hooking into the WordPress request handling code at the appropriate time to take over the request handling yourself.

All standard WordPress requests eventually get broken down to a request to /index.php with a bunch of URL parameters. For example, when someone goes to your blog post at

http://example.com/2009/01/hello-world

WordPress uses the configured permalink structure to break this down to

http://example.com/index.php?year=2008&monthnum=01&name=hello-world

And from that, WordPress can determine which post the request is for, and serve that up accordingly. So what we want to do is be able to construct a request along the lines of

http://example.com/index.php?my-plugin=ajax-handler

and then hook into the WordPress request handling logic so that we can process this request ourselves. Fortunately, WordPress provides an action hook for exactly that purpose, called process_request. Functions that hook into this action are passed one parameter, an instance of the WP class, which encapsulates most of the specific parameters for the current request. If we want to process only the requests which include my-plugin=ajax-handler, we would add something like this to the plugin:

function my_plugin_parse_request($wp) {
    // only process requests with "my-plugin=ajax-handler"
    if (array_key_exists('my-plugin', $wp->query_vars) 
            && $wp->query_vars['my-plugin'] == 'ajax-handler') {

        // process the request.
        // For now, we'll just call wp_die, so we know it got processed
        wp_die('my-plugin ajax-handler!');
    }
}
add_action('parse_request', 'my_plugin_parse_request');

If you’re following along at home, try accessing http://example.com/index.php?my-plugin=ajax-handler. What happens? Most likely, nothing at all… it still loads your normal blog index page. So what went wrong? In order to have the WordPress request handling code process custom URL parameters, we have to register them. This is necessary for a number of reasons including security, performance, and also to ensure that WordPress doesn’t accidentally process something it wasn’t meant to. Fortunately, registering a new query variable is very simple using the query_vars filter hook:

function my_plugin_query_vars($vars) {
    $vars[] = 'my-plugin';
    return $vars;
}
add_filter('query_vars', 'my_plugin_query_vars');

This simply registers ‘my-plugin’ as a valid query variable to be processed by WordPress, but says nothing about valid values for that variable. So now try reloading the page, and you should be greeted with a simple styled page reading “my-plugin ajax-handler!”. Now you just need to modify the my_plugin_parse_request function to actually do your custom request logic, and you’re good to go.

I mentioned earlier that there are a couple of ways to do this. The one caveat to be aware of with the above approach is that you are hooking into the WordPress request processing logic before WordPress has processed the query itself. WordPress’s query handling logic is responsible for examining the request and figuring out what page or post within WordPress the request maps to. This is also what makes the is_* functions work: is_page, is_front_page, is_feed, etc. If your plugin is actually doing things on normal WordPress page requests and needs access to these functions, then instead of hooking into the parse_request action, you should use the wp action. You are still passed an instance of the WP class, so all you need to modify is the add_action call:

add_action('wp', 'my_plugin_parse_request');

I would recommend that you not make this change unless you know that you need to. Otherwise, you’re having WordPress perform a lot of logic that isn’t necessary (including hits against the database), potentially making the request take longer than it needs to be. Though the difference is likely to be imperceptible, it’s just good practice to keep things as fast as possible. And when dealing with custom request handling, you can keep things fast by hooking into as soon in the flow as possible.

Additional Exercise for the reader

If you don’t like the look of URL containing index.php?my-plugin=ajax-handler, and instead want something pretty like

http://example.com/my-plugin/ajax-handler

that is certainly possible with just a little bit more work (see WP_Rewrite). The WordPress OpenID Plugin does this to achieve nice endpoint URLs for the OpenID authentication protocol. A word of caution with this however: if you want to make sure that your plugin works on the widest number of deployments, where you have no idea what their permalink structure is going to be, there is a bit more work that is necessary. You can see the rewrite rules I setup for the OpenID plugin in the common.php file. There’s a lot of other stuff in there, and the rewrite code is a little confusing at parts, but it’s all there. I will actually be changing this in the future to simplify things a bit, so avoid complicating matters unless there is a real reason to.

Further codex reading:

• http://codex.wordpress.org/Query_Overview
• http://codex.wordpress.org/Custom_Queries

So what should plugins do instead? In order to make moving your content folder possible, WordPress 2.6 added a number of constants and functions which refer to the correct location of several often used folders. So instead of including an image using something like:

<img src="<?php bloginfo('wpurl') ?>/wp-content/plugins/my-plugin/images/logo.png" />

you would have:

<img src="<?php echo WP_PLUGIN_URL ?>/my-plugin/images/logo.png" />

or even better:

<img src="<?php echo plugins_url('my-plugin/images/logo.png') ?>" />

Since these constants were added in WordPress 2.6, they obviously won’t work in earlier versions. No problem, you can define them yourself in your plugin. The WordPress Codex page Determining Plugin and Content Directories includes 8 lines of code (plus 1 comment) that you can add to your plugin to ensure these constants are set, even in older versions of WordPress:

// Pre-2.6 compatibility
if ( ! defined( 'WP_CONTENT_URL' ) )
    define( 'WP_CONTENT_URL', get_option( 'siteurl' ) . '/wp-content' );
if ( ! defined( 'WP_CONTENT_DIR' ) )
    define( 'WP_CONTENT_DIR', ABSPATH . 'wp-content' );
if ( ! defined( 'WP_PLUGIN_URL' ) )
    define( 'WP_PLUGIN_URL', WP_CONTENT_URL. '/plugins' );
if ( ! defined( 'WP_PLUGIN_DIR' ) )
    define( 'WP_PLUGIN_DIR', WP_CONTENT_DIR . '/plugins' );

Everywhere else in your plugin, make sure that you use the constants, not the hardcoded path. If the string ‘wp-content’ appears anywhere in your plugin that isn’t defining one of the constants above, you’re doing it wrong. If you also want to make sure the functions like plugins_url are available in older versions of WordPress, see the compatibility.php file the ships with the WordPress OpenID Plugin.

So plugin authors, please go and fix this in your plugins. Please? Otherwise I can’t use your plugin at all on my site.

I’ve spent a lot of time working with the WordPress authentication system. I took over the OpenID plugin for WordPress two years ago, and was hired by Vidoop last May to work on the DiSo Project full time. Last summer, Matt Mullenweg invited me to talk at WordCamp SF 2008 about OAuth. As you can see in my slidedeck, it was a lot of smoke and mirrors at that point… we didn’t have OAuth in WordPress, although it was on the roadmap for 2.7.

We’ve had an OAuth plugin for a little while that Stephen Paul Weber wrote, but it wasn’t until a couple of months ago that I finally sat down to polish it up. The first use-case we wanted to tackled was XML-RPC, so I got to work with Joseph Scott. Having OAuth authentication with XML-RPC would allow for blog clients like MarsEdit or the WordPress iPhone app to communicate with your blog without having to share your WordPress password.

Problem

It wasn’t very long before we butted up against my biggest complaint about the WordPress authentication system — it is very “username/password” centric. There are places in the authentication code where it bails out prematurely if the username or password are missing. This isn’t a problem if your plugin simply wants to authenticate the user against a different password store like LDAP; in fact that works quite well.

The problem is that there are a number of authentication systems widely deployed in the wild (SAML, OpenID, OAuth, etc) that do not fit the standard model of username and password. You can look at the OpenID plugin to see some of the more interesting things that need to be done in order to make it work on the various versions of WordPress. However, when it came to hooking OAuth into the WordPress XML-RPC endpoint, there simply was no way to hack around it… we had to change some of the underlying assumptions.

It’s worth noting one additional requirement we had. Because the wp_authenticate() function, which does most of the heavy lifting for WordPress authentication, resides in pluggable.php it is possible for a plugin to replace the function entirely and authenticate the user however they want. The problem with this solution is that many authentication mechanisms don’t know if they should be invoked without examining the request. If wp_authenticate is replaced, and then the plugin determines it shouldn’t intervene, then it’s already too late. There is no way to pass the function call back to the standard version of wp_authenticate(). This is actually the case for all functions in pluggable.php. One possible solution is to create wrapper functions for everything, which I initially advocated. Instead, Peter Westwood came up with a better solution using a well-established model, which we ended up using for the new authentication system.

Solution

It took far more planning than actual coding, but we finally developed a solution that breaks the dependence on a username and password, but maintains backward compatibility with existing plugins that hook into the authentication code. WordPress 2.8 includes a new filter called authenticate which is passed three parameters: a mixed value (either a WP_User object, a WP_Error object, or null), along with the username and password (either or both of which may be null). All of the standard WordPress authentication logic has been moved into two functions that implement this filter, both with relatively low priority.

• wp_authenticate_username_password() (priority 20) includes the standard logic for authenticating using a standard username and password. It still calls the wp_authenticate_user filter, so plugins that rely on that should be fine. This function also performs the check for an empty username or password.

• wp_authenticate_cookie() (priority 30) is only added into the filter chain when the user is authenticating via wp-login.php and does the normal checking for the WordPress authentication cookie.

Both of these functions first check to see if the first parameter passed in is a valid WP_User object, and immediately stop if it is. This allows plugins to add their own functions into the filter chain which populate the WP_User object using whatever means they see fit. WordPress still takes care of setting the authentication cookie when appropriate, so plugins need only worry with authenticating the user and returning a valid WP_User object.

So what will this look like for plugins? Well, the OAuth plugin for WordPress isn’t finished yet, but the function below should be pretty close to the final version. While there is of course a lot more code for actually implementing OAuth, this is the only hook into the WordPress authentication system needed to make it work. Note that this function doesn’t care about the username and password parameters that are available from the authenticate hook… other plugins may use them.

add_filter('authenticate', 'oauth_authenticate');

/**
 * If the current request was signed using a valid OAuth access token, verify 
 * the request and return the associated user.
 *
 * @param WP_User|WP_Error|null $user authenticated user
 * @return WP_User|WP_Error|null OAuth authenticated user, if request was signed
 */
function oauth_authenticate($user) {
    if (Auth_OAuth_Signer::requestIsSigned()) {
        $oauth_server = oauth_server();
        $user_id = $oauth_server->verify();
        if ($user_id !== false) {
            $user = new WP_User($user_id);
        }
    }   

    return $user;
}

For Plugin Authors

If you’re currently hooking into the WordPress authentication system, especially if you’re providing a custom implementation of wp_authenticate(), take a look at the new authenticate hook. If you are relying on the wp_authenticate action hook, you should also look closely to see if the new hook will do what you need. We left the wp_authenticate hook in place for now, but I’m pretty sure it’s no longer necessary and will likely be removed in future releases. If you are using the wp_authenticate_user hook exclusively, then you’re probably fine, but it’s probably still a good idea to take a look at the new stuff.

So, OAuth in WordPress?

We made additional changes to the WordPress XML-RPC code to make it use the new authentication system appropriately, so it is now possible to hook OAuth into WordPress without any core modifications. We do in fact have a basic OAuth plugin that works with the trunk version of WordPress. However, I don’t think I’m going to push to have the OAuth code included in WordPress 2.8 for two reasons:

• the OAuth libraries are in flux right now. There have been two main PHP libraries that people have used for OAuth, both with their own strengths and weaknesses. I’m currently working with the oauth-php community to combine these libraries using the best parts from each, and a new clean architecture. This effort can be found on github. (This library also requires PHP5 which is a deal breaker for WordPress… not sure how we’ll manage that.)

• Because OAuth has the potential to be such an important part of how third party clients interact with a WordPress blog, I want to make sure we get this right. Personally, I’d feel much more comfortable getting some real world experience with this code in a slightly more constrained environment by releasing it as a plugin first. Once we’ve done that and are comfortable with how it integrates into WordPress (plugin API, admin interface, database schema, etc), I’m all for making it a core part of WordPress.

• I have been listing will.norris.name as my homepage in my various social networks profiles and on blog comments. I’ve built up some Google page rank love through these links, and I want to make sure that is transferred over to willnorris.com. I also want any visitors that go to will.norris.name to be sent over to willnorris.com. The easiest (and correct) way to accomplish both of these is to setup a simple 301 “Moved Permanently” redirect.

• I have also been using will.norris.name as my primary OpenID to login to numerous websites. Many OpenID consumers will allow you to connect multiple OpenIDs or at least change your OpenID, so I can go through them all and update my account. But that will take a while, and I’d like to combine my domains now. The problem is that if I go ahead and setup a 301 redirect (as mentioned above), then it breaks my ability to use will.norris.name as an OpenID (see #4 under OpenID Normalization).

So I want Google and other visitors to see a permanent redirect to willnorris.com, but I don’t want to break my ability to use will.norris.name as an OpenID. I was originally planning to use Apache to perform the redirect, and I wasn’t sure if I’d actually be able to find a solution to my problem. Then I started thinking about WordPress request processing, and came up with the following bit of code:

add_action('wp', 'redirect_wp');

function redirect_wp($wp) {
    // only redirect plain home page requests
    if (!is_front_page() && !is_home()) return;
    if (!empty($_SERVER['QUERY_STRING'])) return;

    // don't redirect OpenID requests
    if (stripos($_SERVER['HTTP_ACCEPT'], 'application/xrds+xml') !== FALSE) return;
    if (stripos($_SERVER['HTTP_USER_AGENT'], 'openid') !== FALSE) return;
    if (empty($_SERVER['HTTP_USER_AGENT'])) return;

    wp_redirect('http://willnorris.com/', 301);
    exit;
}

So it’s pretty simple really… First, we only care about requests to the front page. Because I was only using will.norris.name as a one-page identity site, not a full blog, I only need to worry with requests to the front page. If I had been writing blog posts or other pages on this site, I would need to have different logic here. Second, we do some basic detection for OpenID requests — things like the content negotiation header for XRDS, or the “openid” string that appears in the user agent of JanRain OpenID libraries. If it doesn’t look like an OpenID request, we go ahead and redirect to willnorris.com.

Now of course this only works in my specific use case, but perhaps it will prove useful for others. For what it’s worth, the new work we’re doing on metadata discovery with XRD would prevent this problem, since we’re moving away from overloading normal HTTP requests where possible.

Update: I now also treat an empty user agent string as an OpenID request. This covers Blogger, which uses the OpenID4Java library. I’m fairly certain all major search engine spiders include a user agent, so this should be a fairly safe addition.

Additional Note for FastCGI Users

It’s worth noting as well that WordPress loses the HTTP status code when using FastCGI, as is used at Joyent. A comment in the code claims that it causes problems with some FastCGI setups, but I’ve not experienced that. This is very important, because Google will not transfer your page rank repuation if only using a 302 “Moved Temporarily” redirect; it must be a 301. A quick fix for this is to add the following to the very beginning of the above code:

add_filter('wp_redirect_status', 
    create_function('$s', 'status_header($s); return $s;'));

Choosing the right hostname

Part of my custom setup is that I have a whole slew of bogus hostnames pointing to localhost, which Apache then dynamically maps to the correct document root. For the most part, I just drop the TLD from the actual hostname… so http://willnorris/ is my locally hosted development site for this blog http://willnorris.com/, and http://will.norris/ is my development site for http://will.norris.name/. I also keep a handful of WordPress versions running locally, so I can test plugins in those different environments — http://wordpress-2.3/, http://wordpress-2.5/, etc. When I began to setup my WordPress MU (and BuddyPress) instance, I used the site http://wpmu/. The installation went fine, but when I tried to login it failed every time. Given that this same setup worked fine with single-user WordPress, I was quite confused. I quickly realized though, that the authentication cookies were never being set for WPMU… in fact no cookies were.

The difference between the two versions of WordPress is the value of COOKIE_DOMAIN which is passed to setcookie(). Both flavors of WordPress allow you to define this constant in wp-config.php, but they differ in what happens if it is not defined there. WordPress sets it to the boolean false, whereas WordPress MU sets it to '.'.$current_site->domain. This results in a different Set-Cookie HTTP header between the two. Take for example the wordpress_test_cookie cookie. WordPress sends the response header

Set-Cookie: wordpress_test_cookie=WP+Cookie+check; path=/

whereas WordPress MU sends the response header

Set-Cookie: wordpress_test_cookie=WP+Cookie+check; path=/; domain=.wpmu

The difference of course is the domain=.wpmu there on the end. In a production environment, this wouldn’t make a bit of difference. But because I’m using fake hostnames in a development environment, this makes all the difference in the world. You see, the HTTP Cookie Spec (Section 4.3.2 Rejecting Cookies) requires that the domain attribute includes an “embedded dot”. This is a security feature that prevents a site from setting a cookie on a top level domain like “.com”. Since single-user WordPress wasn’t specifying a domain attribute, it didn’t have any problem setting the cookie. Because my hostname wpmu doesn’t contain an embedded dot, the browser was properly rejecting the cookies, preventing me from being able to login. So our solution here was to use the site http://wp.mu/ (note the added dot in the middle) for hosting our WordPress MU development site.

Sending Mail

The other main problem I had with WordPress MU was that none of the notification emails were being delivered. This was actually a problem with single-user WordPress as well, but it didn’t matter as much then. Now I’m needing to test the account sign-up process a bit more, and so I need the activation emails that are being sent out. It’s been a long time since I’ve administered an email server, so I won’t embarrass myself by trying to explain what the problem was (something along the lines of my ISP’s SMTP server not liking what mail() was sending) . I was however able to fix it by writing a very simple plugin, Development Mailer, that changes a few configuration options of PHPMailer. This works for me on Mac OS X (Leopard), but I make no guarantees for anyone else. Keep in mind that his plugin should only ever be needed for a development environment… if you’re unable to send notification emails from your production blog, then you’ve got other problems.

• Don’t use OpenID at all
• Use the local OpenID provider built in to the plugin
• Delegate to another OpenID

If a the local OpenID provider is used, it also supports transmitting sreg attributes pulled from the user’s WordPress profile and the DiSo Profiles plugin, if it’s installed. The user can update this data before releasing it to the relying party, but those changes aren’t currently stored. In addition, trust decisions are recorded and stored for the user, and can be modified from their config page at any time.

If a user chooses to delegate to another OpenID, they need only provide the delegate OpenID itself. All server configuration and supported extensions from that provider are discovered and published in the local XRDS document. Of course this data will have to be cached and probably updated on some interval, but it makes setting up delegation a breeze.

Server Modes

Remember that every user’s OpenID is their author posts URL. So what about the home URL for the blog itself? Well, the OpenID server can operate in two basic modes: multi-user and blog-owner… perhaps not the best names, but they’ll work for now.

In multi-user, the default configuration, the server supports a feature in OpenID 2.0 called OpenID Provider driven identifier selection. What this means is that ANY user on that blog can enter the home URL as their OpenID, and the OpenID provider itself will make sure that the correct identifier is returned to the relying party. The final identifier will still be something like http://example.com/author/admin/, but the user only needs to enter example.com at a relying party. If you’ve used ever used Yahoo’s OpenID provider, then you’ve probably seen how this works.

I suspect the more common mode will be blog-owner, which is appropriate for personal blogs. Even if there are multiple users in the system, the blog is basically owned by one individual and it makes sense for that individual to use the blog home URL as their OpenID. This mode is activated by selecting a “Blog Owner” on the main plugin configuration page. Once set, this user’s personal OpenID configuration (whether turned off, using the local provider, or delegated to another OpenID) will be used at the blog home URL. Other user’s on the blog could still use their OpenIDs, but they would need to type in the full URL each time… they just lose the convenience of being able to use the blog home URL.

For security, once a blog owner is set, no other user can update the setting. The blog owner can set someone else as the new blog owner (a push mechanism), but no-one can take ownership away (a pull mechanism). Additionally, if a multi-user blog wants to ensure no-one is ever set as the blog owner, they can add the following to their wp-config.php file:

define("OPENID_DISALLOW_OWNER", 1);

What’s left to do

The main outstanding work to be done before release is the user interface. You’ll notice that the user’s configuration screen (where they manage their external OpenIDs, OpenID Provider preference, and Trusted Sites) is a bit confusing if you’re not to familiar with OpenID. The current layout was done simply for convenience while developing the OpenID Provider, and will be overhauled to some degree before the release.

I’m also not too sure about compatibility with older versions of PHP and WordPress. I’ve been developing using PHP 5.2.6, MySQL 5.0.51, and WordPress 2.6.1. I do intend to remain as backwards compatible on these as possible (within reason), but make no guarantees for the current development code. I’ll also be working to make everything compatible with WordPressMU and BuddyPress. For now, I just wanted to get the code out there, and get people playing with it a little bit.

Simplified Database Structure

Version 1.0 of wp-openid added four new database tables and overloaded one of the comment table fields in a weird way. Version 2.0 required only three of those four tables and added one column to the comment table to eliminate the overloaded field. The current development version doesn’t add any columns or overload fields of existing tables, and adds only one new table of its own, which I’m still hoping to eliminate.

The two removed tables were used to store OpenID associations and nonces, both of which are temporary data necessary to make OpenID security actually work. Instead of using these tables, I’ve opted to use an updated version of the OpenID store used in Simon Willison’s mu-open-id plugin which uses the WordPress options table to store this data. I’ve updated his store to use the latest php-openid APIs as well as to reduce the potential for race conditions.

I’ve removed the column from the comments table that was tracking which comments were left using OpenIDs, and am instead storing this in the postmeta table for the post the comment is associated with. It would certainly be preferable to have a commentmeta table, but I like this better than the previous solution.

The one remaining table is the identity table which tracks the identity URLs of each user. I would like to store this in the usermeta table, but because it requires unique keys there’s just not a real clean way to do this and keep the plugin scalable to support large deployments. If this is fixed in 2.7, we could theoretically eliminate any custom database stuff in the plugin, which I’d absolutely love.

Removed PEAR_LOG

For the time being I’ve removed PEAR_LOG and am simply using error_log() for what logging still remains. The problem is that most people weren’t taking advantage of the logs anyway, so they were just taking up space. I’ll likely look at making use of the WP_DEBUG constant to allow more verbose logging when it’s desired. For now this just simplifies things a bit, and eliminates at least one case of library conflict that was reported.

Code Refactoring

Really? More refactoring? Didn’t I just do a lot of this in the last point release? Well yes, but more was needed… MUCH more. Previously, code was roughly divided based on the MVC (model, view, controller) model into store.php, interface.php, and logic.php, respectively. That worked for a while, but got to be pretty confusing as those individual files became a bit unmanageable. Instead, things are now broken into more logical segments… comments, admin panel, logging in through wp-login.php, etc. This seems to be a lot easier to manage and more importantly, easier to extend.

More Hooks

I haven’t sat down to document them all yet, but I’m adding in more hooks for other plugins to add functionality. Want to pull profile data from FOAF instead of sreg? No problem, now you have a hook you can implement. This makes everything in the plugin much more lightweight and “loosely joined” which is always good. All of the existing non-core OpenID functionality (like SREG) is currently using these hooks.

Bug Fixes

Though I’m not always good about replying, I generally do monitor the conversations on the WordPress support forums. I will try and put together a more exhaustive list of what bugs have been addressed, but I will simply say for now that most of the major bugs people have reported there should be absent from the current development branch.