IIS Authentication plugin for the Wordpress PHP blogging engine
This weekend, I was working on an MSDN magazine article and as part of putting together a demo happened to install PHP’s Wordpress blog app on IIS7. Of course, I used the latest FastCGI bits available in the box in in Windows Server 2008 Beta 3, and the latest Windows-optimized PHP 5.2.3 build from www.php.net. Long story short, I ended up writing a Wordpress plugin that allows Wordpress to use IIS authentication methods, including forms authentication.
I was pretty happy to observe that Wordpress installed and worked seamlessly on Windows Server 2008. To install it, I ended up doing the following:
1. Check Wordpress requirements.
2. Install MySql Community Server 5.1 and associated GUI tools. I disabled TCP connectivity, and enabled named pipes only since I was using it locally.
NOTE: When trying to connect to the MySql instance using the MySql Administrator, be sure to use “.” as server name, not “localhost”. Use “root” as username with the password you set up. Click Advanced and enable named pipes to connect, and specify the instance name as the pipe name (“MySql” for me).
3. Download latest PHP 5.2.3, Windows Non-Thread-Safe build.
4. Follow the Wordpress “Famous 5 minute install” steps, creating the MySql DB using the MySql command line tool. Be sure to write down the "admin" user's password that wordpress generates.
5. Create IIS site, rooted at the wordpress directory root. Put it on localhost, with “myphpblog” host-header binding. Added the host-header to %windir%\system32\drivers\etc\hosts file so I can test with http://myphpblog/ locally.
6. Added “index.php” default document to the site
7. Set up the PHP via FastCGI handler mapping as I describe in the PHP with FastCGI article.
I have to admit that I’ve never written any PHP code worth mentioning before, since most of my development is split pretty evenly between C# (for .NET) and C++. However, PHP seems to be a pretty simple language to get started with, especially if you are not in need of using any extensions that would require some learning about.
Wordpress itself provides a pretty neat extensibility model, allowing you to drop in plugins that either replace the definition of some Wordpress functions (such the most of the ones used for authenticating users), and intercept other events via filter and action hooks. Most of these are not extremely well documented, so it took a bit of time of groveling through Wordpress code to figure them out. Thankfully, findstr makes pretty quick work on finding function references in plain text .PHP files, so a few NY minutes later the hook stuff becomes clear enough to get started.
In the end, I didn’t end up using Wordpress for the article (nothing bad against Wordpress, but I found another app more suitable for my demo), but not before I ended up writing the Wordpress IIS Authentication plugin.
IIS Auth plugin for Wordpress
In a nutshell, the plugin allows Wordpress to recognize IIS authentication methods, allowing the user to log in with an IIS authentication method such as Windows Authentication, Basic Authentication, or the ASP.NET forms authentication.
The Wordpress blog engine would then recognize the IIS user and use it for things like writing posts, leaving comments, or performing blog administration.
This is nice because it allows you to integrate the app with the rest of your website which may be using a particular IIS or ASP.NET authentication mechanism, so that users log into wordpress the same exact way they log into the rest of your application.
NOTE that the user account still has to created in with Wordpress, so that it can do internal access control when the username is provided to it by the IIS Auth plugin. A complete solution would basically completely remove the need to maintain the user accounts with Wordpress, and use whatever credential store the IIS authentication mechanism was using instead, but doing this (if it is at all possible) was out of scope for me. Perhaps, one day someone could build a WP plugin that replaces its credential store with one that uses ASP.NET’s Membership service, and thus works with different credential stores (hint hint).
To illustrate this, here is what happens when I click the WP login link after setting up the IIS Auth plugin, and configuring ASP.NET forms authentication for the blog website:
As you can see, I can login in with my makeshift ASP.NET login page with the unskinned Login control. I can now log into Wordpress by logging into my website with my ASP.NET Membership credentials.
If I configure basic authentication instead, I get:
As you can see, I can log in with basic authentication instead of the Wordpress login form.
Step by step installation instructions
1. Set up an IIS authentication method you want to use to access Wordpress.
If you are using IISAuth, you probably already have this set up. I tested with both Windows Authentication, Basic Authentication, and Forms Authentication. You can configure this using the IIS7 Admin tool – select the website/application node where WP is installed, and click the Authentication feature icon. Here is me configuring Forms Authentication:
Admittedly the process is easier for using Windows Auth or Basic Auth, if you don’t already have Forms authentication / Membership set up. I used forms auth with a sample XML Membership provider – you can find it in the attached sample application.
Also note that I am leaving Anonymous Authentication enabled for now, because I am going to need it to be able to access Wordpress until I the IIS Auth plugin is activated.
2. Create the “admin” user so you can access the WP admin console and create other users as necessary without locking yourself out J
If using basic or windows authentication, create the admin windows user, and make sure to make it a Member of IIS_IUSRS. DO NOT give this user Administrator privileges on the machine, or make it a member of the Administrators or other powerful groups. You should also disable the right of this user to do interactive logons to the machine. This is just a user with which we will log into Wordpress to create other users / perform administrative tasks for the blog once we turn on IIS Auth.
I used Forms authentication / membership so I went and created a Membership user. You can create one from the IIS7 Admin tool by clicking the .NET Users feature (if you are using the built-in SqlMembershipProvider). The Admin tool won’t let you create a user for a non-GACed Membership provider, so you would have to create it yourself using code or your website’s user registration page.
3. Drop the IISauth.php plugin into the wp-content\plugins\iisauth directory (create it since it won’t exist)
4. Go the WP administration console , and log in with the WP’s “admin” user (the password was created and given to you when you installed wordpress. Don’t lose it! If you don’t have it, reinstall).
5. Click the plugins link on the top, and on the plugins screen, activate the IIS Auth plugin
You should see a message telling you that the plugin has been activated. At this point, the IIS Auth plugin is in effect, and whenever you click the login link, you will be prompted to log in using whatever IIS authentication method you configured.
6. OPTIONAL: Disable Anonymous Authentication if needed
If you are not using Forms Authentication, at this point you can go back to the IIS7 Admin tool, like we did in step 1, and disable anonymous authentication. Do this only if you want all access to Wordpress to require the user to log in.
If you are OK with the user browsing WP anonymously, until login is required, leave anonymous authentication on (most cases). The user will be challenged to log in as soon as Wordpress determines that they should be logged in, such as when you try to access the admin part of the blog, or when you click the Login link.
7. Create other Wordpress users for each IIS user that you want to be able to log into Wordpress
Use the “admin” user to log into WP’s admin console, and then you can create a user for each of the IIS users you want to have Wordpress accounts.
Download IIS Auth plugin for Wordpress
Download IIS Auth for Wordpress, version 1.0. This download contains a sample application, with a sample XML membership provider, forms auth login page, and the IIS Auth plugin located in the wp-content\plugins\iisauth\iisauth.php. You can copy this into your wordpress root to get started, and examine the web.config.sample for the desired settings – or just grab the iisauth plugin from there.
As usual, this is released under the Microsoft Permissive License, which means that this is distributed as is, with no warranties, and you can do whatever you want with the code, as long as you retain this license and all attributions present in the software.
Quick limitations of version 1.0:
1. You can use this on IIS 5, IIS6, and IIS7, although using it with Forms Authentication requires an application running using IIS7 Integrated pipeline. You can still use it on IIS5/6 for Windows Authentication or Basic Authentication.
2. Logout for Forms Authentication requires a login.aspx page in the root of the site, that supports the ?action=logout querystring parameter and performs Forms Authentication logout.
3. Logout for all other authentication methods is performed by asking you to close the browser window. This is how logout must be performed for basic authentication, or windows authentication, since the browser caches the logon credentials and not all browsers correctly clear the cache.
That’s it – happy blogging. Leave any bug reports, feature requests, and other feedback here.
Thanks,
Mike
For the past 5 years, I was the core Program Manager for Microsoft ASP.NET 2.0 and IIS 7.0 products. I drove the design and development of the IIS 7.0 web server core, the IIS FastCGI support, the AppCmd command line tool, the ASP.NET Integrated pipeline, and other special projects around server security, performance, and scalability. Now, I am working on my own on cutting edge web server tech on top of the Microsoft IIS platform, and continue blogging about it here.