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
- 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
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:
- In the Return URL field, enter the URL to the wp-login.php file in your WordPress site. For example:
- 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.
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
After downloading the ACS WordPress Plugin, open the acs-wp-plugin-config-sample.php file.
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.
For the ACS_APPLICATION_REALM constant, enter the realm that you entered when adding your WordPress site as a relying party application (e.g.
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
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
# protect acs-wp-plugin-config.php
deny from all
Enabling the Plugin
Copy the acs-plugin-for-wordpress folder to the /wp-content/plugins/ folder in your WordPress installation.
In a web browser, navigate to your WordPress site and log in as an administrator.
In the site administration area, click Plugins in the left navigation menu. The ACS Plugin for WordPress should be displayed.
ACS Plugin for WordPress, click Activate. The ACS WordPress plugin is now enabled on your site.
Testing the Plugin
To test the plugin, log out of the WordPress site
and select Log in again on the main page of the site.
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.
Log in using one of the identity providers.
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.
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.
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.