Composr Tutorial: Integrating Composr into a network via HTTP authentication

Written by Chris Graham
Image

Authentication is required to even reach the web application

Authentication is required to even reach the web application

(Click to enlarge)

Image

Authentication via HTTP

Authentication via HTTP

(Click to enlarge)

On a normal Composr installation (a Composr powered website), whatever forum system is being used contains member details in its database; Composr authenticates to this, using custom forum drivers to tackle the differing systems. For users to login to these, they need to enter their details, in either the forum, or Composr, and then Composr can maintain the login using login cookies and/or sessions (propagated by URL or session cookies).

Sometimes, however, for additional security and/or integration reasons, it is desirable to be able to login via the HTTP authentication screen present in web browsers. Composr allows this form of login (maintenance status) (if using the Conversr system), in a platform independent way: therefore it may be accomplished by any web server scheme, such as Apache .htaccess, or IIS account-integrated security.

Table of contents

  1. Composr Tutorial: Integrating Composr into a network via HTTP authentication
    1. HTTP authentication in Composr
    2. Instructions
    3. Apache instructions
      1. Remove maintenance script htaccess code if it exists
      2. If you want to protect the entire site
      3. If you want a public welcome zone
    4. See also

HTTP authentication in Composr

Security Tip

Note that when using HTTP authentication, the username and passwords are available in plain text to any PHP script that can exist in the same domain as the Composr installation: although you would normally trust those with the ability to write PHP scripts on your domain, make sure you consider this ability for them to read anyone's password.

If enabled, any new HTTP-Auth user Composr sees, is added to Composr, after Composr collects some additional details for that user (including the desired username to connect to the HTTP-auth username, and their e-mail address). Note that by the time Composr sees a page view, the HTTP-authentication scheme has already guaranteed that it is by a real, authenticated user. Once the activation information has been collected, no form of additional login is ever required for any zone controlled by HTTP authentication (although it is possible to override the HTTP authentication with a manual login if desired, for example, by staff).

Note: Account completion is not considered the same as joining. Members will by put into all default usergroups, but the Composr feature for giving members a choice of usergroup is not supported (that feature is only for members that join manually, as it requires a two-form join process, and we designed HTTP-auth profile completion to just be one-form).

Instructions

Image

Enabling HTTP-authentication recognition in Composr

Enabling HTTP-authentication recognition in Composr

(Click to enlarge)

Image

You will likely want to disable joining Composr, so only HTTP-auth members may use it

You will likely want to disable joining Composr, so only HTTP-auth members may use it

(Click to enlarge)

In order to use HTTP authentication, it must first be enabled via the "HTTP-Auth is enabled" configuration option. It is likely you will also wish to deny permission to access the join page (in the Welcome zone); this isn't strictly necessary for any kind of security reason because only an HTTP-auth user may access a restricted area of Composr by nature of the HTTP-auth itself (as it runs 'above' Composr in terms of system layering), but it is cleaner to avoid problems that may result in users creating secondary accounts.

Unlike Composr LDAP integration, HTTP-auth members do not inherit any usergroups from the HTTP authentication system, as HTTP authentication does not define any such membership. Therefore you have full control over what usergroups members are of, once their account has become known to Composr (when it has been activated by a user authenticating under the associated HTTP-auth username). You cannot change the password of an HTTP-auth user, because Composr does not consider such a bound account to have a password. You also cannot log-out from an HTTP-auth user, although you can forcibly login as a normal user to create an override. HTTP-auth users may be edited as necessary (by editing their bound profiles), including banning them if desired.

Image

Upon first login, members must complete their profile, if the "Ensure completed profiles" configuration option (Admin Zone > Setup > Configuration > User/usergroup options > Log in) is enabled

Upon first login, members must complete their profile, if the "Ensure completed profiles" configuration option (Admin Zone > Setup > Configuration > User/usergroup options > Log in) is enabled

(Click to enlarge)

You can either protect your whole site with HTTP-authentication, or individual zones:
The default Composr install is intentionally split into different zones, such that the Welcome Zone is minimalistic, and most site functionality is contained in the site zone. This allows you to use the Welcome Zone (located at your base URL) as a non-logged-in 'welcome' page available to anyone, while restricting all other zones (and possibly the uploads directory or subdirectories there-of) with HTTP-authentication. Composr does not need any special configuration itself for this, and will simply bind to an HTTP-auth user only when it sees one is being used and when it sees that there is no normal-user override (i.e. you don't have a manual Composr login in addition to HTTP-authentication).

As previously mentioned, but worth re-iterating: Composr is only accessible in HTTP-auth enabled areas if the user is actually able to HTTP-authenticate there. Composr will then assume the associated user is logged in. If Composr cannot see any HTTP-auth user, it can only be because that Composr zone is not secured with HTTP-auth.
This takes some time to get-your-head-around, but makes sense when you do. If it helps, consider the situation like this: with HTTP-authentication, security and authentication is being taken away from Composr and moved to another layer – it puts Composr in a position to be able to make assumptions by placing a virtual shield in front of it.

Apache instructions

These instructions apply only to Apache web server users.

Remove maintenance script htaccess code if it exists

Before adding in our HTTP-Auth directives into the .htaccess file (the file in Composr's base directory), we must first remove any code created by the “Auto-maintained maintenance script IP-barrier” config option. It is not compatible with HTTP-Auth. If you see anything in the file that looks like the following, remove it:

e.g. .htaccess:

Code

<FilesMatch ^((rootkit_detection|upgrader|uninstall|data/upgrader2|config_editor|code_editor)\.php)$>
Require all denied
... (Require ip directives here) ...
</FilesMatch>

If you want to protect the entire site

Define your HTTP-auth settings in the .htaccess file (the file in Composr's base directory) within the <RequireAll> section, under the IP bans comment and all IP ban listings.

e.g. .htaccess:

Code

<RequireAll>
... (IP ban comments and directives here) ...
AuthType Basic
AuthName "Restricted Content"
AuthUserFile /var/www/.htpasswd
require valid-user
</RequireAll>
We have to give an absolute path for the Apache AuthUserFile setting. This is a little annoying but it's an Apache requirement. These files can be generated using online tools or Linux commands (see links under "See also").

If you want a public welcome zone

You must define the core HTTP-auth settings (i.e. define the AuthType, AuthName, AuthUserFile) only once in the main .htaccess file (the file in Composr's base directory).

e.g. .htaccess:

Code

<RequireAll>
... (IP ban comments and directives here) ...
AuthType Basic
AuthName "Restricted Content"
AuthUserFile /var/www/.htpasswd
</RequireAll>

We have to give an absolute path for the Apache AuthUserFile setting. This is a little annoying but it's an Apache requirement. These files can be generated using online tools or Linux commands (see links under "See also").

Then place only (*) the actual restrictions on the files placed within individual zones, and the data directory also (†).

e.g. site/.htaccess:

Code

require valid-user

* You must not redefine the Apache Auth* settings separately for each zone because it will make the web browser treat each zone and the data directory as having separate logins, causing a lot of repeated requests for re-authentication.
† It is key the data directory is given it else parts of Composr will not function correctly due to inconsistent login state across frames)

One further note about the Welcome Zone: If you use the shoutbox or poll blocks, these make calls to the data directory (which you will have secured via HTTP-auth), which will prompt for logins. Also the preview function on the Guestbook will do this too. To resolve this problem, copy the data/preview.php and data/iframe.php files to the base directory; Composr will then be smart enough to find the right ones to use based on the zone the user is in.


See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.