| 1 | === HTTP Authentication === |
|---|
| 2 | Contributors: dwc |
|---|
| 3 | Tags: authentication |
|---|
| 4 | Requires at least: 3.0 |
|---|
| 5 | Tested up to: 3.3.1 |
|---|
| 6 | Stable tag: 4.4 |
|---|
| 7 | |
|---|
| 8 | Use an external authentication source in WordPress. |
|---|
| 9 | |
|---|
| 10 | == Description == |
|---|
| 11 | |
|---|
| 12 | The HTTP Authentication plugin allows you to use existing means of authenticating people to WordPress. This includes Apache's basic HTTP authentication module, [Shibboleth](http://shibboleth.internet2.edu/), and many others. |
|---|
| 13 | |
|---|
| 14 | To follow updates to this plugin, visit: |
|---|
| 15 | |
|---|
| 16 | http://danieltwc.com/ |
|---|
| 17 | |
|---|
| 18 | For help with this version, visit: |
|---|
| 19 | |
|---|
| 20 | http://danieltwc.com/2011/http-authentication-4-0/ |
|---|
| 21 | |
|---|
| 22 | == Installation == |
|---|
| 23 | |
|---|
| 24 | 1. Login as an existing user, such as admin. |
|---|
| 25 | 2. Upload the `http-authentication` folder to your plugins folder, usually `wp-content/plugins`. (Or simply via the built-in installer.) |
|---|
| 26 | 3. Activate the plugin on the Plugins screen. |
|---|
| 27 | 4. Add one or more users to WordPress, specifying the external username for the Nickname field. Also be sure to set the role for each user. |
|---|
| 28 | 5. Logout. |
|---|
| 29 | 6. Protect `wp-login.php` and `wp-admin` using your external authentication (using, for example, `.htaccess` files). |
|---|
| 30 | 7. Try logging in as one of the users added in step 4. |
|---|
| 31 | |
|---|
| 32 | Note: This version works with WordPress 3.0 and above. Use the following for older versions of WordPress: |
|---|
| 33 | |
|---|
| 34 | * Wordpress 2.0: [Version 1.8](http://downloads.wordpress.org/plugin/http-authentication.1.8.zip) |
|---|
| 35 | * Wordpress 2.5 through 2.9.x: [Version 2.4](http://downloads.wordpress.org/plugin/http-authentication.2.4.zip) |
|---|
| 36 | |
|---|
| 37 | == Frequently Asked Questions == |
|---|
| 38 | |
|---|
| 39 | = What authentication mechanisms can I use? = |
|---|
| 40 | |
|---|
| 41 | Any authentication mechanism which sets the `REMOTE_USER` (or `REDIRECT_REMOTE_USER`, in the case of ScriptAlias'd PHP-as-CGI) environment variable can be used in conjunction with this plugin. Examples include Apache's `mod_auth` and `mod_auth_ldap`. |
|---|
| 42 | |
|---|
| 43 | = How should I set up external authentication? = |
|---|
| 44 | |
|---|
| 45 | This depends on your hosting environment and your means of authentication. |
|---|
| 46 | |
|---|
| 47 | Many Apache installations allow configuration of authentication via `.htaccess` files, while some do not. Try adding the following to your blog's top-level `.htaccess` file: |
|---|
| 48 | `<Files wp-login.php> |
|---|
| 49 | AuthName "WordPress" |
|---|
| 50 | AuthType Basic |
|---|
| 51 | AuthUserFile /path/to/passwords |
|---|
| 52 | Require user dwc |
|---|
| 53 | </Files>` |
|---|
| 54 | |
|---|
| 55 | (You may also want to protect your `xmlrpc.php` file, which uses separate authentication code.) |
|---|
| 56 | |
|---|
| 57 | Then, create another `.htaccess` file in your `wp-admin` directory with the following contents: |
|---|
| 58 | `AuthName "WordPress" |
|---|
| 59 | AuthType Basic |
|---|
| 60 | AuthUserFile /path/to/passwords |
|---|
| 61 | Require user dwc` |
|---|
| 62 | |
|---|
| 63 | In both files, be sure to set `/path/to/passwords` to the location of your password file. For more information on creating this file, see below. |
|---|
| 64 | |
|---|
| 65 | = Where can I find more information on configuring Apache authentication? = |
|---|
| 66 | |
|---|
| 67 | See Apache's HOWTO: [Authentication, Authorization, and Access Control](http://httpd.apache.org/docs/howto/auth.html). |
|---|
| 68 | |
|---|
| 69 | = How does this plugin authenticate users? = |
|---|
| 70 | |
|---|
| 71 | This plugin doesn't actually authenticate users. It simply feeds WordPress the name of a user who has successfully authenticated through Apache. |
|---|
| 72 | |
|---|
| 73 | To determine the username, this plugin uses the `REMOTE_USER` or the `REDIRECT_REMOTE_USER` environment variable, which is set by many Apache authentication modules. If someone can find a way to spoof this value, this plugin is not guaranteed to be secure. |
|---|
| 74 | |
|---|
| 75 | By default, this plugin generates a random password each time you create a user or edit an existing user's profile. However, since this plugin requires an external authentication mechanism, this password is not requested by WordPress. Generating a random password helps protect accounts, preventing one authorized user from pretending to be another. |
|---|
| 76 | |
|---|
| 77 | = If I disable this plugin, how will I login? = |
|---|
| 78 | |
|---|
| 79 | Because this plugin generates a random password when you create a new user or edit an existing user's profile, you will most likely have to reset each user's password if you disable this plugin. WordPress provides a link for requesting a new password on the login screen. |
|---|
| 80 | |
|---|
| 81 | Also, you should leave the `admin` user as a fallback, i.e. create a new account to use with this plugin. As long as you don't edit the `admin` profile, WordPress will store the password set when you installed WordPress. |
|---|
| 82 | |
|---|
| 83 | In the worst case scenario, you may have to use phpMyAdmin or the MySQL command line to [reset a user's password](http://codex.wordpress.org/Resetting_Your_Password). |
|---|
| 84 | |
|---|
| 85 | = Can I configure the plugin to support standard WordPress logins? = |
|---|
| 86 | |
|---|
| 87 | Yes. You can authenticate some users via an external, single sign-on system and other users via the built-in username and password combination. (Note: When mixed authentication is in use, this plugin does not scramble passwords as described above.) |
|---|
| 88 | |
|---|
| 89 | When you configure your external authentication system, make sure that you allow users in even if they have not authenticated externally. Using [Shibboleth](http://shibboleth.internet2.edu/) as an example: |
|---|
| 90 | `AuthName "Shibboleth" |
|---|
| 91 | AuthType Shibboleth |
|---|
| 92 | Require Shibboleth` |
|---|
| 93 | |
|---|
| 94 | This enables Shibboleth authentication in ["passive" mode](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPProtectContent). |
|---|
| 95 | |
|---|
| 96 | Then, in WordPress: |
|---|
| 97 | |
|---|
| 98 | 1. Set the plugin to allow WordPress authentication. |
|---|
| 99 | 2. Configure the login URI to match your Shibboleth system. For example, if your blog is hosted at `http://example.com/`, then your login URI should be `http://example.com/Shibboleth.sso/Login?target=%redirect_encoded%`. |
|---|
| 100 | 3. Configure the logout URI to match your Shibboleth system. Following the above example, your logout URI would be `http://example.com/Shibboleth.sso/Logout?return=%redirect_encoded%`. |
|---|
| 101 | |
|---|
| 102 | After saving the options, authentication will work as follows: |
|---|
| 103 | |
|---|
| 104 | * If a user is already authenticated via Shibboleth, and he or she exists in the WordPress database, this plugin will log them in automatically. |
|---|
| 105 | * If a user is not authenticated via Shibboleth, the plugin will present the standard WordPress login form with an additional link to login via Shibboleth. |
|---|
| 106 | |
|---|
| 107 | Other authentication systems (particularly those without a login or logout URI) will need to be configured differently. |
|---|
| 108 | |
|---|
| 109 | = Does this plugin support multisite (WordPress MU) setups? = |
|---|
| 110 | |
|---|
| 111 | Yes, you can enable this plugin across a network or on individual sites. However, options will need to be set on individual sites. |
|---|
| 112 | |
|---|
| 113 | If you have suggestions on how to improve network support, please submit a comment. |
|---|
| 114 | |
|---|
| 115 | = How do you handle staged deployments (dev, test, prod) with the plugin? = |
|---|
| 116 | |
|---|
| 117 | If you have a WordPress site with multiple environments (e.g. `dev.example.com`, `test.example.com`, and `example.com`) you can use additional variables in the login and logout URIs: |
|---|
| 118 | |
|---|
| 119 | * `%host%` - The current value of `$_SERVER['HTTP_HOST']` |
|---|
| 120 | * `%base%` - The base domain URL (everything before the path) |
|---|
| 121 | * `%site%` - The WordPress home URI |
|---|
| 122 | * `%redirect%` - The return URI provided by WordPress |
|---|
| 123 | |
|---|
| 124 | You can also use `%host_encoded%`, `%site_encoded%`, and `%redirect_encoded%` for URL-encoded values. |
|---|
| 125 | |
|---|
| 126 | For example, your login URI could be: |
|---|
| 127 | |
|---|
| 128 | `https://%host%/Shibboleth.sso/Login?target=%redirect_encoded%` |
|---|
| 129 | |
|---|
| 130 | This would be modified for each environment as appropriate. |
|---|
| 131 | |
|---|
| 132 | == Screenshots == |
|---|
| 133 | |
|---|
| 134 | 1. Plugin options, allowing WordPress authentication |
|---|
| 135 | 2. WordPress login form with external authentication link |
|---|
| 136 | |
|---|
| 137 | == Changelog == |
|---|
| 138 | |
|---|
| 139 | = 4.4 = |
|---|
| 140 | * Update CSS to correctly center login button on WordPress 3.3 |
|---|
| 141 | |
|---|
| 142 | = 4.3 = |
|---|
| 143 | * Update plugin URIs |
|---|
| 144 | |
|---|
| 145 | = 4.2 = |
|---|
| 146 | * Declare support for WordPress 3.2.1 |
|---|
| 147 | * Extend variable replacement for staged deployments |
|---|
| 148 | * Wrap redirect parameter on login to force us through `wp-login.php` so we can check the external authentication (thanks to Josh Larios) |
|---|
| 149 | |
|---|
| 150 | = 4.1 = |
|---|
| 151 | * Declare support for WordPress 3.2 |
|---|
| 152 | * Update screenshots for WordPress 3.2 |
|---|
| 153 | |
|---|
| 154 | = 4.0 = |
|---|
| 155 | * Restore (and improve) support for falling back to WordPress password authentication |
|---|
| 156 | * Remove migration of old options format (we'll assume enough people have upgraded) |
|---|
| 157 | |
|---|
| 158 | = 3.3 = |
|---|
| 159 | * Update options handling to better support WordPress MU |
|---|
| 160 | |
|---|
| 161 | = 3.2 = |
|---|
| 162 | * Restore password generation for adding and editing users |
|---|
| 163 | |
|---|
| 164 | = 3.1 = |
|---|
| 165 | * Bump version number to make 3.0.1 the latest version on wordpress.org |
|---|
| 166 | |
|---|
| 167 | = 3.0.1 = |
|---|
| 168 | * Handle authentication cookies more gracefully |
|---|
| 169 | |
|---|
| 170 | = 3.0 = |
|---|
| 171 | * Add support for WordPress 3.0 |
|---|
| 172 | * Update WordPress MU support for WordPress 3.0 |
|---|
| 173 | |
|---|
| 174 | = 2.4 = |
|---|
| 175 | * Add support for WordPress MU (Elliot Kendall) |
|---|
| 176 | * Allow for mixed HTTP and built-in authentication by falling back to wp-login.php (Elliot Kendall) |
|---|
| 177 | |
|---|
| 178 | == Upgrade Notice == |
|---|
| 179 | |
|---|
| 180 | = 4.4 = |
|---|
| 181 | Minor CSS fix for WordPress 3.3 |
|---|
| 182 | |
|---|
| 183 | = 4.3 = |
|---|
| 184 | No code changes; updating plugin URIs |
|---|
| 185 | |
|---|
| 186 | = 4.2 = |
|---|
| 187 | Extends support for variable replacement |
|---|
| 188 | |
|---|
| 189 | = 4.1 = |
|---|
| 190 | Minor update for WordPress 3.2 |
|---|
