Code Sample: WordPress Plugin

Article
11/09/2015

Updated: June 19, 2015

Applies To: Azure

The ACS WordPress Plugin allows WordPress hosts to use ACS to enable federated login for their WordPress sites.

WordPress administrators can use Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS) to create trust relationships between their sites 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 renders a custom login page based on the ACS configuration and enables end users to use an identify provider of their choice to log in to the WordPress site.

To download the WordPress plugin, see http://wordpress.org/extend/plugins/acs-plugin-for-wordpress/

Features

Authenticate to WordPress by using Windows Live ID, Facebook, Google, Yahoo!, or a 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

A Microsoft Azure account at the Azure homepage.
An Access Control namespace. For more information, see How to: Create an Access Control Namespace.
Web host running PHP 5.0 or later
Web host running WordPress 3.0 or later

Configuring the ACS WordPress Plugin

There are three parts of configuring the ACS WordPress Plugin:

Configuring ACS for the WordPress Plugin
Configuring the WordPress Plugin settings
Enabling the WordPress Plugin

Configuring ACS for the WordPress Plugin

You can use the ACS Management Portal to configure ACS.

To configure ACS for the WordPress plugin

Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)
To create an Access Control namespace, click New, click App Services, click Access Control, and then click Quick Create. (Or, click Access Control Namespaces before clicking New.)
To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

This action opens the Access Control Service management portal.
To establish relationships with the identity providers you would like the users of your website to use when logging in, click Identity providers and then select an identity provider for your site.
To register your WordPress site with ACS, click Relying party applications, click Add, enter the following information in the form, and then click Save.
- 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, select 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. The key will no longer be valid on this date
- Leave the other fields at their default values.
Next, create the rules that determine the user information that ACS sends to your site. In this example, we send all claims issued by the identity providers. To create this rule, click Rule groups, click Default Rule Group for My WordPress Site, and then click Generate. Verify that your identity providers are selected and click Generate again.

Important

It is critically important that the input claim type uniquely identifies the user. If you are not sure which claim type to use, contact the administrator of your identity provider.

If you are using a custom WS-Federation identity provider, such as AD FS 2.0, ensure that there is a rule that returns a nameidentifier claim from this identity provider. This claim sends the unique ID of the user to the WordPress application. If this rule is absent, you must create a rule that maps the unique ID claim returned by that identity provider to the nameidentifier claim type.

Configuring the WordPress Plugin Settings

To configure the WordPress plugin settings

Download the WordPress Plugin from the WordPress site at http://wordpress.org/extend/plugins/acs-plugin-for-wordpress/
Open the acs-wp-plugin-config-sample.php file in the downloaded folder.
In the ACS_NAMESPACE field, enter the full-qualified domain name of your Access Control namespace, such as mynamespace.accesscontrol.windows.net. To find the domain name, in the ACS portal, click Application integration. The value appears in the Management Portal field of the Endpoint Reference section.
For the ACS_APPLICATION_REALM constant, enter the realm that you entered when you registered your WordPress site with ACS as a relying party application, for example, http://127.0.0.1/wordpress/.
In the ACS_TOKEN_SIGNING_KEY field, enter the token signing key that you created when you registered your WordPress site as a relying party application. Treat this key in a secure manner, as you would a password.
Save the file as acs-wp-plugin-config.php.

Important

The acs-wp-plugin-config.php file contains sensitive information that must be protected from unauthorized users. We recommend that you set appropriate permissions on this file 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 the acs-wp-plugin-config.php file.
```
# protect acs-wp-plugin-config.php
<files acs-wp-plugin-config.php>
order allow,deny
deny from all
</files>
```

Enabling the WordPress Plugin

To enable the WordPress 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. The ACS Plugin for WordPress page appears.
Under ACS Plugin for WordPress, click Activate. The ACS WordPress plugin is now enabled on your site.

Testing the WordPress Plugin

To test the WordPress plugin

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

The login page displays one button for each identity provider that you configured in ACS.
Select an identity provider and log in..
When you are authenticated, you will be asked to create a user name for the WordPress site. If you logged in using Windows Live ID, you will also be asked to enter an e-mail address.

A new WordPress account with the Subscriber role is created and you are redirected to your WordPress profile page. For subsequent visits, click the identity provider to log in. You will not be prompted to enter a user name or email address.

Note

An administrator account can promote federated subscriber accounts to administrator status, so you use a federated account to administer the site.

Notes

The unique ID that Windows Live ID creates for each user is specific to your Access Control namespace. If you replace your Access Control namespace with an Access Control namespace that has a different name, users who authenticated with a Windows Live ID account cannot log in to your site. In the unlikely event that you need to change the Access Control namespace, these users can still use the WordPress password reset feature to sign in using a local password.