modules/pubcookie/README.txt

//$Id: README.txt,v 1.7 2007/02/27 22:27:06 jvandyk Exp $

Pubcookie module
================
By jvandyk at iastate.edu

DESCRIPTION
-----------
This module integrates pubcookie-based authentication with Drupal.

For more information about pubcookie, see http://pubcookie.org.

PREREQUISITES
-------------
Before using this module, make sure that your pubcookie environment
is set up and running correctly.

The best way to do this is to create a subdirectory on your webserver
with an HTML file and an .htaccess file in it. The .htaccess file
would look something like this:

Authname "Testing"
PubcookieAppID foo
Authtype NetID  <-- or whatever Authtype your organization uses
Require valid-user

Upon trying to access the HTML file, Apache should redirect you
to your pubcookie server, and upon authentication the pubcookie
server will redirect back to your HTML file. When all that is
working, you are ready to try pubcookie.module.

INSTALLATION
------------
Place the entire pubcookie module folder into your third-party modules
directory, typically at sites/all/modules.

Enable the module in Drupal by going to Administer -> Site building ->
Modules.

Set up pubcookie.module by going to Administer -> Site configuration -> 
Pubcookie.

Enable the pubcookie login block by going to Administer -> Site building ->
Blocks.

Ensure that Clean URLs are enabled at Administer -> Site configuration ->
Clean URLs.

ID/E-MAIL EQUIVALENCY
---------------------
Checking the ID/E-mail equivalency checkbox says that the distributed
login ID, such as jsmith@example.edu, is also a valid email address.
In some cases the distributed IDs are not valid email addresses
(for example, your drupal.org ID is not a valid email address).
If this box is checked, during the registration process the pubcookie
module will insert the user's ID into the mail column of the user table.

LDAP INTEGRATION
----------------
LDAP is integrated into pubcookie module. If you don't want to use LDAP,
leave the LDAP server setting blank.

To have profile fields automatically populated by LDAP when users
register, name the Form Name of the profile field to be the same
as the LDAP directory field name. For example, if your LDAP directory
returns a field called "displayname" containing the user's full name,
go to Administer -> User management -> Profiles and create a textfield 
with the form name "profile_displayname".

AUTO-USERNAME ASSIGNMENT
------------------------
By default Drupal gives new users registering via distributed authentication
a username that is the same as their distributed authentication ID.
You may not want this. For one thing, if a user makes a post and the
user's username is joe@example.edu and that is a real email address
(see ID/E-MAIL EQUIVALENCY, above), that real email address will now
appear in "submitted by" links and be picked up by hungry web crawlers.

By assigning an LDAP field to be used as username, this problem is avoided.

GOTCHAS
-------
If you check the ID/E-mail equivalency checkbox so the mail column of the
user table is populated, and if you have local users with the same email
address, you cannot update the accounts through Administer -> User management
-> edit because Drupal says "The email address joe@example.edu is already
registered." That is because email addresses must be unique in the user table.

TROUBLESHOOTING
---------------
If you see the message "Pubcookie request received over non-secure protocol"
while trying to login, you probably haven't created the directory and
.htaccess file that pubcookie's "Login directory" setting points to.
Or you may not have clean URLs enabled; e.g., your login link is pointing
to q=/login/pc when you want it to point to /login/pc.

WHY IT WORKS
------------
When you click on the Log In link provided by the pubcookie block, it takes
you to the directory you specified for "Login directory" under admin >
settings > pubcookie (by default, 'login'). The pubcookie module takes
this path, adds "pc" (an arbitrary string) to the end of it and -- and
here's the key -- registers it as a menu item in the menu hook. So now
http://yourdomain.com/login/pc is not a nonexistent file but a registered
Drupal path that is "located" inside a directory that's protected by a
.htaccess file restricting the contents to pubcookie-server-authenticated
users. So when you reach that path, the pubcookie module receives a call
to pubcookie_page() and goes from there.
1	//$Id: README.txt,v 1.7 2007/02/27 22:27:06 jvandyk Exp $
2
3	Pubcookie module
4	================
5	By jvandyk at iastate.edu
6
7	DESCRIPTION
8	-----------
9	This module integrates pubcookie-based authentication with Drupal.
10
11	For more information about pubcookie, see http://pubcookie.org.
12
13	PREREQUISITES
14	-------------
15	Before using this module, make sure that your pubcookie environment
16	is set up and running correctly.
17
18	The best way to do this is to create a subdirectory on your webserver
19	with an HTML file and an .htaccess file in it. The .htaccess file
20	would look something like this:
21
22	Authname "Testing"
23	PubcookieAppID foo
24	Authtype NetID <-- or whatever Authtype your organization uses
25	Require valid-user
26
27	Upon trying to access the HTML file, Apache should redirect you
28	to your pubcookie server, and upon authentication the pubcookie
29	server will redirect back to your HTML file. When all that is
30	working, you are ready to try pubcookie.module.
31
32	INSTALLATION
33	------------
34	Place the entire pubcookie module folder into your third-party modules
35	directory, typically at sites/all/modules.
36
37	Enable the module in Drupal by going to Administer -> Site building ->
38	Modules.
39
40	Set up pubcookie.module by going to Administer -> Site configuration ->
41	Pubcookie.
42
43	Enable the pubcookie login block by going to Administer -> Site building ->
44	Blocks.
45
46	Ensure that Clean URLs are enabled at Administer -> Site configuration ->
47	Clean URLs.
48
49	ID/E-MAIL EQUIVALENCY
50	---------------------
51	Checking the ID/E-mail equivalency checkbox says that the distributed
52	login ID, such as jsmith@example.edu, is also a valid email address.
53	In some cases the distributed IDs are not valid email addresses
54	(for example, your drupal.org ID is not a valid email address).
55	If this box is checked, during the registration process the pubcookie
56	module will insert the user's ID into the mail column of the user table.
57
58	LDAP INTEGRATION
59	----------------
60	LDAP is integrated into pubcookie module. If you don't want to use LDAP,
61	leave the LDAP server setting blank.
62
63	To have profile fields automatically populated by LDAP when users
64	register, name the Form Name of the profile field to be the same
65	as the LDAP directory field name. For example, if your LDAP directory
66	returns a field called "displayname" containing the user's full name,
67	go to Administer -> User management -> Profiles and create a textfield
68	with the form name "profile_displayname".
69
70	AUTO-USERNAME ASSIGNMENT
71	------------------------
72	By default Drupal gives new users registering via distributed authentication
73	a username that is the same as their distributed authentication ID.
74	You may not want this. For one thing, if a user makes a post and the
75	user's username is joe@example.edu and that is a real email address
76	(see ID/E-MAIL EQUIVALENCY, above), that real email address will now
77	appear in "submitted by" links and be picked up by hungry web crawlers.
78
79	By assigning an LDAP field to be used as username, this problem is avoided.
80
81	GOTCHAS
82	-------
83	If you check the ID/E-mail equivalency checkbox so the mail column of the
84	user table is populated, and if you have local users with the same email
85	address, you cannot update the accounts through Administer -> User management
86	-> edit because Drupal says "The email address joe@example.edu is already
87	registered." That is because email addresses must be unique in the user table.
88
89	TROUBLESHOOTING
90	---------------
91	If you see the message "Pubcookie request received over non-secure protocol"
92	while trying to login, you probably haven't created the directory and
93	.htaccess file that pubcookie's "Login directory" setting points to.
94	Or you may not have clean URLs enabled; e.g., your login link is pointing
95	to q=/login/pc when you want it to point to /login/pc.
96
97	WHY IT WORKS
98	------------
99	When you click on the Log In link provided by the pubcookie block, it takes
100	you to the directory you specified for "Login directory" under admin >
101	settings > pubcookie (by default, 'login'). The pubcookie module takes
102	this path, adds "pc" (an arbitrary string) to the end of it and -- and
103	here's the key -- registers it as a menu item in the menu hook. So now
104	http://yourdomain.com/login/pc is not a nonexistent file but a registered
105	Drupal path that is "located" inside a directory that's protected by a
106	.htaccess file restricting the contents to pubcookie-server-authenticated
107	users. So when you reach that path, the pubcookie module receives a call
108	to pubcookie_page() and goes from there.