This project is read-only.

ACS WordPress Plugin Readme

The ACS WordPress Plugin allows WordPress hosts to enable federated login for their WordPress site using Windows Azure AppFabric Access Control Service (ACS) 2.0.

WordPress administrators can use ACS to create trust relationships between their site and identity providers such as Windows Live ID, Facebook, Google, Yahoo!, and custom identity providers such as Microsoft Active Directory Federation Services 2.0. The ACS WordPress Plugin then renders a custom login page based on the ACS configuration, and enables end users to log in to the WordPress site using an identity provider of their choice.

This plugin is available for download at http://wordpress.org/extend/plugins/acs-plugin-for-wordpress/

Features 

  • Authenticate to WordPress using Windows Live ID, Facebook, Google, Yahoo!, and custom web-based identity providers configured in ACS
  • Easy registration for WordPress site subscribers
  • Manage the WordPress site using a federated account
  • Federated accounts are identical to normal user accounts and support fallback to local password-based authentication
  • Integrates with ACS using the WS-Federation protocol and Simple Web Tokens

Requirements

Configuring the ACS WordPress Plugin

There are three parts to configuring the ACS WordPress Plugin:

  • Configuring Access Control Service
  • Configuring Plugin Settings
  • Enabling the Plugin

Configuring Access Control Service

The ACS configuration required for this sample can be performing using the ACS management portal.

1. Open a browser and navigate to http://windows.azure.com and sign in. From there, navigate to the Service Bus, Access Control, and Caching section to configure your ACS service namespace. Once you have created a namespace, select it and click Manage > Access Control Service at the top of the page. This should launch the following page in a new window: 

2. The first step in configuring ACS is to establish relationships with the identity providers you would like the users of your website to use when logging in. To do this, click on the Identity Providers link and add the identity providers you want to feature on your site. When finished, click Home to return to the main page. 

3. Next, register your WordPress site with ACS by creating a relying party application. Click the Relying Party Applications link on the main page, then select Add and enter the following information in the subsequent form:

  • In the Name field, enter a display name for your site.
  • In the Realm field, enter the base URL of your WordPress site. For example: http://127.0.0.1/wordpress/
  • In the Return URL field, enter the URL to the wp-login.php file in your WordPress site. For example: http://127.0.0.1/wordpress/wp-login.php
  • In the Token Format field, select SWT. This configures ACS to send a Simple Web Token (SWT) to the WordPress plugin whenever a user successfully authenticates.
  • In the Identity Providers field, check all of the identity providers that you want to support on your site.
  • In the Token Signing Key field, click Generate to create a token signing key. Copy this key for use later in the plugin configuration.
  • In the Expiration Date field, enter an appropriate expiration date for the key. At this date, the key will no longer be valid.
  • Leave the other fields at their default values.

When complete, click the Save button and then navigate back to the main page.  

4. With your relying party application registered, it is now time to create the rules that determine what user information ACS will pass to your site. In this example, we will simply pass through all the claims issued by all of the identity providers (e.g. Yahoo!, Google, Windows Live ID). To do this, click Rule Groups from the main page, and click Default Rule Group for My WordPress Site (or whatever you named your site). At the bottom of the subsequent page, click the Generate link. Ensure that all of your identity providers are selected and click Generate again. Finally, click Save and navigate back to the main page.

Important: If you are using a custom WS-Federation identity provider (such as AD FS 2.0), ensure there is a rule that outputs a nameidentifier claim from this identity provider. This claim will carry the unique ID of the user to the WordPress application. If this rule is absent, then you must create a rule that maps the unique ID claim returned by your identity provider to the nameidentifier claim type. The example rule below transforms a UPN (user principle name) claim into the required nameidentifier claim:

It is critically important that the input claim type is one that is used to transmit a unique user ID. If you are not sure of which claim type to use, then contact the administrator of your identity provider.

Configuring Plugin Settings

1. After downloading the ACS WordPress Plugin, open the acs-wp-plugin-config-sample.php file.

2. For the ACS_NAMESPACE constant, enter the full-qualified domain name for your ACS namespace (e.g. mynamespace.accesscontrol.windows.net). This information is in the URL when you are using the ACS portal, and is also displayed in the Application Integration section of the ACS portal.

3. For the ACS_APPLICATION_REALM constant, enter the realm that you entered when adding your WordPress site as a relying party application (e.g. http://127.0.0.1/wordpress/).

4. For the ACS_TOKEN_SIGNING_KEY constant, enter the token signing key that you created when adding your WordPress site as a relying party application. Treat this as you would a password.

5. Save the file as acs-wp-plugin-config.php.

Important: The acs-wp-plugin-config.php file contains sensitive information that needs to be protected from unauthorized users. It is strongly recommended that you set the permissions on this file to not be world-readable, and configure your web server to deny direct access to this file via the browser. For Apache web servers, copy the code below into a file named .htaccess and place it in the same directory as acs-wp-plugin-config.php:

 

# protect acs-wp-plugin-config.php
<files acs-wp-plugin-config.php>
order allow,deny
deny from all
</files>

 

Enabling the Plugin

1. Copy the acs-plugin-for-wordpress folder to the /wp-content/plugins/ folder in your WordPress installation.

2. In a web browser, navigate to your WordPress site and log in as an administrator.

3. In the site administration area, click Plugins in the left navigation menu. The ACS Plugin for WordPress should be displayed.

4. Under ACS Plugin for WordPress, click Activate. The ACS WordPress plugin is now enabled on your site.

Testing the Plugin

1. To test the plugin, log out of the WordPress site and select Log in again on the main page of the site.

2. In the login page, you should now see login buttons for the identity providers that you configured in ACS. Select the identity provider you want to log in with. 

 

3. Log in using one of the identity providers.

4. Once completed, you will be asked to create a username for the Wordpress site. If you logged in using Windows Live ID, you will also be asked to enter an email address.

5. Once completed, you will have a new Wordpress account created with the role of “subscriber”, and will be redirected to your WordPress profile page. For subsequent visits, simply click on the identity provider to log in (you will not be prompted to enter a username or email address a second time).

Note: An administrator account can promote federated subscriber accounts to administrator status, so it is possible to administer the site using a federated account.

Notes

Below are important notes about the current version of the ACS Wordpress plugin.

  • The unique ID that Windows Live ID creates for each user is specific to your ACS namespace. If you replace your ACS namespace with an ACS namespace of a different name, then users who previously authenticated using a Windows Live ID account will not be able to log in to your site. In the unlikely event that you need to change the ACS namespace used, these users can still use the WordPress password reset feature to sign in using a local password instead.

Last edited Apr 15, 2011 at 8:43 PM by asmalser, version 9

Comments

okami Aug 26, 2013 at 2:59 PM 
Hi all. I would like to use this plugin, however it is not working with the latest version of WP since it is still trying to include registraiton.php. And registration.php is deprecated since version 3.1

Is there anyone who could help with a new version of the plugin, or info on how to address this?

Thanks,

Christian

pvandorp Apr 27, 2011 at 8:16 AM 
Nevermind ;-) I found out I was still running on PHP4. Changing the version to PHP5 did the trick.

pvandorp Apr 27, 2011 at 7:36 AM 
Has anyone got this to work yet? I'm stumbling on a fatal error when I try to activate the plugin saying that there was an "unexpected '{' on line 61" in 'acs-wp-plugin.php'. I haven't touched this file myself. I checked my config file to see if I haven't forgotten any ')' or ';' somewhere, but that wasn't the case.