modules/securesite/README.txt

$Id: README.txt,v 1.3 2008/10/23 21:03:02 darrenoh Exp $

The Secure Site module allows site administrators to make a site or part of a
site private. You can restrict access to the site by role. This means the site
will be inaccessible to search engines and other crawlers, but you can still
allow access to certain people.

You can also secure remote access to RSS feeds. You can keep content private and
protected, but still allow users to get notification of new content and other
actions via RSS with news readers that support user:pass@example.com/node/feed
URLs, or have direct support for user name and password settings. This is
especially useful when paired with the Organic Groups module or other node
access systems.


Installation
------------

  1. Place the entire securesite directory into your sites/all/modules
     directory.

  2. Enable the Secure Site module by navigating to:

     Administer >> Site building >> Modules

  3. Configure the Secure Site permissions:

     Administer >> User management >> Permissions

     Set the user roles that are allowed to access secured pages by giving those
     roles the "access secured pages" permission.

  4. Configure the Secure Site module:

     Administer >> Site configuration >> Secure Site


Configuration
-------------

  - Force authentication

    This setting controls whether users will be forced to authenticate before
    viewing pages. By default, authentication is never forced.

    1. Never

       This setting will prevent Secure Site from hiding pages.

    2. Always

       This setting will hide your entire site from unauthenticated users.

    3. During maintenance

       This setting will hide your site during maintenance.

    4. On restricted pages

       This setting will hide only pages that anonymous users cannot access.

  - Authentication type

    Three methods of authentication are available. Please note that HTTP
    authentication requires extra configuration if PHP is not installed as an
    Apache module. See the Known issues section of this file for details.

    1. HTTP digest

       This will enable HTTP digest authentication. The user's browser will
       prompt for the user's name and password before displaying the page.

       Digest authentication protects a user's password from eavesdroppers when
       you are not using SSL to encrypt the connection. However, it can only be
       used when a copy of the password is stored on the server. For security
       reasons, Drupal does not store passwords. You will need to configure
       scripts to securely save passwords and authenticate users. See README.txt
       in the digest_md5 directory for details.

       When digest authentication is enabled, passwords will be saved when users
       log in or set their passwords. If you use digest authentication to
       protect your whole site, you should allow guest access or allow another
       authentication type until users whose passwords are not yet saved have
       logged in. Otherwise, you may lock yourself out of your own site.

    1. HTTP basic

       This will enable HTTP basic authentication. The user's browser will
       prompt for the user's name and password before displaying the page.
       Basic authentication is not secure unless you are using SSL to encrypt
       the connection.

    2. Use HTML log-in form

       This method uses a themeable HTML log-in form for user name and password
       input. This method is the most reliable as it does not rely on the
       browser for authentication. Like HTTP basic, it is insecure unless you
       are using SSL to encrypt the connection.

    HTTP authentication is recommended for secure feeds, because feed readers
    are not likely to be able to handle forms. You can enable all three types of
    authentication at the same time.

  - Digest authentication script

    For security, HTTP digest authentication uses an external script to check
    passwords. Enter the digest authentication script exactly as it would appear
    on the command line.

  - Password storage script

    For security, HTTP digest authentication uses an external script to save
    passwords. Enter the password storage script exactly as it would appear on
    the command line.

  - Authentication realm

    You can use this field to name your login area. This is primarily used with
    HTTP Auth.

  - Guest user name and password

    If you give anonymous users the "access secured pages" permission, you can
    set a user name and password for anonymous users. If not set, guests can use
    any name and password.

  - Customize HTML forms

    "Custom message for login form" and "Custom message for password reset form"
    are used in the HTML forms when they are displayed. If the latter box is
    empty, Secure Site will not offer to reset passwords. Please note, the login
    form is only displayed when the HTML login form authentication mode is used.


Theming
-------

Secure Site's HTML output is controlled by three files:

- securesite-page.tpl.php: Template for Secure Site pages. Works in the same way
  as page.tpl.php.

- securesite-user-login.tpl.php: Template for the user log-in form.

- securesite-user-pass.tpl.php: Template for the password reset form.

You can theme Secure Site's HTML output by copying these files to your theme's
directory. The files in your theme's directory will become the templates for all
Secure Site HTML output.


Configuring cron jobs
---------------------

If HTTP authentication is forced, cron jobs will need to authenticate
themselves. See http://drupal.org/cron for more details on configuring cron
jobs. These examples show how to add a user name and password:

45 * * * * /usr/bin/lynx -auth=username:password -source http://example.com/cron.php
45 * * * * /usr/bin/wget --user=username --password=password -O - -q http://example.com/cron.php
45 * * * * /usr/bin/curl --user username:password --silent --compressed http://example.com/cron.php


Known issues
------------

  - Authentication on PHP/CGI installations

    If you are using HTTP Auth and are unable to login, PHP could be running in
    CGI mode. When run in CGI mode, the normal HTTP Auth login variables are not
    available to PHP. To work-around this issue, add the following rewrite rule
    at the end of the .htaccess file in Drupal's root installation directory:

    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

    After making the suggested change in Drupal 6, the rewrite rules would
    look like this:

    # Rewrite URLs of the form 'x' to the form 'index.php?q=x'.
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} !=/favicon.ico
    RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

  - Authentication when running Drupal via IIS

    If you are using HTTP Auth and are unable to login when Drupal is running on
    an IIS server, make sure that the PHP directive cgi.rfc2616_headers is set
    to 0 (the default value).

1	$Id: README.txt,v 1.3 2008/10/23 21:03:02 darrenoh Exp $
2
3	The Secure Site module allows site administrators to make a site or part of a
4	site private. You can restrict access to the site by role. This means the site
5	will be inaccessible to search engines and other crawlers, but you can still
6	allow access to certain people.
7
8	You can also secure remote access to RSS feeds. You can keep content private and
9	protected, but still allow users to get notification of new content and other
10	actions via RSS with news readers that support user:pass@example.com/node/feed
11	URLs, or have direct support for user name and password settings. This is
12	especially useful when paired with the Organic Groups module or other node
13	access systems.
14
15
16	Installation
17	------------
18
19	1. Place the entire securesite directory into your sites/all/modules
20	directory.
21
22	2. Enable the Secure Site module by navigating to:
23
24	Administer >> Site building >> Modules
25
26	3. Configure the Secure Site permissions:
27
28	Administer >> User management >> Permissions
29
30	Set the user roles that are allowed to access secured pages by giving those
31	roles the "access secured pages" permission.
32
33	4. Configure the Secure Site module:
34
35	Administer >> Site configuration >> Secure Site
36
37
38	Configuration
39	-------------
40
41	- Force authentication
42
43	This setting controls whether users will be forced to authenticate before
44	viewing pages. By default, authentication is never forced.
45
46	1. Never
47
48	This setting will prevent Secure Site from hiding pages.
49
50	2. Always
51
52	This setting will hide your entire site from unauthenticated users.
53
54	3. During maintenance
55
56	This setting will hide your site during maintenance.
57
58	4. On restricted pages
59
60	This setting will hide only pages that anonymous users cannot access.
61
62	- Authentication type
63
64	Three methods of authentication are available. Please note that HTTP
65	authentication requires extra configuration if PHP is not installed as an
66	Apache module. See the Known issues section of this file for details.
67
68	1. HTTP digest
69
70	This will enable HTTP digest authentication. The user's browser will
71	prompt for the user's name and password before displaying the page.
72
73	Digest authentication protects a user's password from eavesdroppers when
74	you are not using SSL to encrypt the connection. However, it can only be
75	used when a copy of the password is stored on the server. For security
76	reasons, Drupal does not store passwords. You will need to configure
77	scripts to securely save passwords and authenticate users. See README.txt
78	in the digest_md5 directory for details.
79
80	When digest authentication is enabled, passwords will be saved when users
81	log in or set their passwords. If you use digest authentication to
82	protect your whole site, you should allow guest access or allow another
83	authentication type until users whose passwords are not yet saved have
84	logged in. Otherwise, you may lock yourself out of your own site.
85
86	1. HTTP basic
87
88	This will enable HTTP basic authentication. The user's browser will
89	prompt for the user's name and password before displaying the page.
90	Basic authentication is not secure unless you are using SSL to encrypt
91	the connection.
92
93	2. Use HTML log-in form
94
95	This method uses a themeable HTML log-in form for user name and password
96	input. This method is the most reliable as it does not rely on the
97	browser for authentication. Like HTTP basic, it is insecure unless you
98	are using SSL to encrypt the connection.
99
100	HTTP authentication is recommended for secure feeds, because feed readers
101	are not likely to be able to handle forms. You can enable all three types of
102	authentication at the same time.
103
104	- Digest authentication script
105
106	For security, HTTP digest authentication uses an external script to check
107	passwords. Enter the digest authentication script exactly as it would appear
108	on the command line.
109
110	- Password storage script
111
112	For security, HTTP digest authentication uses an external script to save
113	passwords. Enter the password storage script exactly as it would appear on
114	the command line.
115
116	- Authentication realm
117
118	You can use this field to name your login area. This is primarily used with
119	HTTP Auth.
120
121	- Guest user name and password
122
123	If you give anonymous users the "access secured pages" permission, you can
124	set a user name and password for anonymous users. If not set, guests can use
125	any name and password.
126
127	- Customize HTML forms
128
129	"Custom message for login form" and "Custom message for password reset form"
130	are used in the HTML forms when they are displayed. If the latter box is
131	empty, Secure Site will not offer to reset passwords. Please note, the login
132	form is only displayed when the HTML login form authentication mode is used.
133
134
135	Theming
136	-------
137
138	Secure Site's HTML output is controlled by three files:
139
140	- securesite-page.tpl.php: Template for Secure Site pages. Works in the same way
141	as page.tpl.php.
142
143	- securesite-user-login.tpl.php: Template for the user log-in form.
144
145	- securesite-user-pass.tpl.php: Template for the password reset form.
146
147	You can theme Secure Site's HTML output by copying these files to your theme's
148	directory. The files in your theme's directory will become the templates for all
149	Secure Site HTML output.
150
151
152	Configuring cron jobs
153	---------------------
154
155	If HTTP authentication is forced, cron jobs will need to authenticate
156	themselves. See http://drupal.org/cron for more details on configuring cron
157	jobs. These examples show how to add a user name and password:
158
159	45 * * * * /usr/bin/lynx -auth=username:password -source http://example.com/cron.php
160	45 * * * * /usr/bin/wget --user=username --password=password -O - -q http://example.com/cron.php
161	45 * * * * /usr/bin/curl --user username:password --silent --compressed http://example.com/cron.php
162
163
164	Known issues
165	------------
166
167	- Authentication on PHP/CGI installations
168
169	If you are using HTTP Auth and are unable to login, PHP could be running in
170	CGI mode. When run in CGI mode, the normal HTTP Auth login variables are not
171	available to PHP. To work-around this issue, add the following rewrite rule
172	at the end of the .htaccess file in Drupal's root installation directory:
173
174	RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
175
176	After making the suggested change in Drupal 6, the rewrite rules would
177	look like this:
178
179	# Rewrite URLs of the form 'x' to the form 'index.php?q=x'.
180	RewriteCond %{REQUEST_FILENAME} !-f
181	RewriteCond %{REQUEST_FILENAME} !-d
182	RewriteCond %{REQUEST_URI} !=/favicon.ico
183	RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]
184	RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
185
186	- Authentication when running Drupal via IIS
187
188	If you are using HTTP Auth and are unable to login when Drupal is running on
189	an IIS server, make sure that the PHP directive cgi.rfc2616_headers is set
190	to 0 (the default value).
191