modules/multisite_login/README.txt

$Id: README.txt,v 1.1.2.1.2.1 2008/11/04 22:37:51 dalin Exp $


** OVERVIEW **

Multisite Login allows a user to login to all sites in a multisite configuration, even though the
multisites do not share domain names.  

For example:
  politicker.com
  politickernj.com
  politickerny.com
  etc.

NOTE: if you are using several sites on the same domain (ex. politicker.com, nj.politicker.com, 
ny.politicker.com, etc.), then you do not need this module.  The multisite functionality in Drupal
core has the ability to share logins for sites like these without additional modules. 

This module was designed to be an alternative to the singlesignon module
but using a technique that does not block search engines from accessing your websites.


** REQUIREMENTS **

You must be:
  - using a multisite installation
  - using a separate database for each site (no table prefixing, though the code could be 
    modified to allow for this, patches welcome). 
  - sharing the users table across all sites (If this is not you, what are you hoping that this module
    will do for you?)


** INSTALLATION **

1)  Install and setup multisite_api before using this module.

2)  Adjust the settings in multisite_api to control which sites are logged in to.  Multisite_login
    will login to all sites that match the current site's visibility and server. 

3)  Install and enable this module and multisite_api on all of your sites.

4)  Make sure that you are sharing the user and multisite_login tables on all of your sites.  The
    $db_prefix in the settings.php files of your secondary sites will look something like this:

      $db_prefix = array(
        'default' => '',
        'users' => 'master_db.',
        'multisite_login' => 'master_db.',
        // You may share other tables here.
      );

    Note that if you are sharing the sessions table between your sites, then you should also share
    the multisite_login_sessions table.

4)  Login to one of the sites

5)  If you are an administrator, you will see a string of single-pixel images at the bottom of the
    page, one for each partner site (If you are not an admin, the images are hidden via CSS techniques). A black image indicates a successfull login, red means failure.  Check admin/logs/watchdog on the partner site to see why a login failed.


** HAVING PROBLEMS? **

1)  I get "user/pass does not match" errors.

    Make sure you are sharing the multisite_login table, Review the installation steps above.

2)  I get "The host does not match" errors.

    In rare circumstances, usually only in a development environment, IPs from the same browser
    session may not in fact match.  Go to admin/multisite/multisite_login and disable host matching.

3)  I just copied my database from staging to production and now I can't get one or more sites to
    work.

    Clear the multisite_api cache on those sites by visiting:
    admin/multisite/multisite_api
    And saving the form.

4)  It just doesn't work.  My sites are in a subdirectory of the main domain, or are accessed on a
    special port.

    When Multisite Login creates the URLs that point to the images on the other sites it has to do a
    bit of guesswork.  Normally it will use the name of site directory as the domain of the other
    site. However this doesn't work if the other site is in a sub-directory, or if the other site
    uses a non-standard port.  In these cases you must set $base_url in your settings.php files, and then go to the multisite api settings page and save the form (this clears the cache).

5)  It works in some browsers / for some of  my users, but not others.

    Make sure that the browser is not blocking 3rd party cookies.

6)  I have some other problem.

    1)  Install the simpletest module 6.2.x or later.
        http://drupal.org/project/simpletest
    2)  Run all multisite simpletests
    3)  Report your bug to the Drupal issue queue and attach the results of the simpletest and a
        screenshot of all watchdog entries created during the simpletest.


** TECHNIQUE **

When a user logs into a site, the returned html will include several image tags, one for each partner
site. The url of the image will include a query string which provides enough information to login the
user on the partner site. A cookie belonging to the partner site is then stored on the user's browser.
Partner sites return 1x1 images.

* Originating Site *

On hook_user $op == login
- query each partner site via image tag
- img src has a query string that includes: double-munged password, uid, and the session id encoded
  in a reversable hash

* Partner Site *

Via a menu callback
- Check if uid/md5 match
- Check if IP matches what is stored in the session table for the given session id
- Check that the timestamp is recent
- Check that this sid hasn't been tried before
- log the user in
- store the sid so it can't be used again for a multisite login
- return image
- exit(0);

* Considerations *
We are passing a double MD5ed password, though not theoretically impossible to reverse engineer,
if someone really wants to break into your site they would use a method that requires less work.
If the query string _were_ to be somehow obtained by a third party, it could not be used by the
third party to masquerade as the original user since logins are only allowed once per session id.


** LOGGING OUT **

Multisite Login does not synchronize logging out accross sites. Consider this scenario:  A user 
logs in to your network of sites.  Chances are high that they will spend most of their time on just 
one site, they might not even vist other sites in the network.  Depending on how you have PHP 
configured, their session will expire on those other sites and they will be automatically logged 
out, even though they remain logged in on the one site.  

Multiste Login cannot control this situation and so it doesn't make any attempt to do anything when
a user explicitly logs out.

However in theory, if uids were stored in {multisite_login_sessions}, a combination of
hook_user $op == 'logout' and hook_cron could be used to log out the user on all sites, patches
welcome.

It is also because of this reason that a user who vists several sites in your network, but at 
inconsistent frequencies may find that they have to re-login to some sites.  


** CREDITS **

This module was developed by

Advomatic
http://advomatic.com

and sponsored by

Politicker
http://politicker.com
+ 50 state sites

and

The New York Observer
http://observer.com
1	$Id: README.txt,v 1.1.2.1.2.1 2008/11/04 22:37:51 dalin Exp $
2
3
4
5	OVERVIEW
6
7	Multisite Login allows a user to login to all sites in a multisite configuration, even though the
8	multisites do not share domain names.
9
10	For example:
11	politicker.com
12	politickernj.com
13	politickerny.com
14	etc.
15
16	NOTE: if you are using several sites on the same domain (ex. politicker.com, nj.politicker.com,
17	ny.politicker.com, etc.), then you do not need this module. The multisite functionality in Drupal
18	core has the ability to share logins for sites like these without additional modules.
19
20	This module was designed to be an alternative to the singlesignon module
21	but using a technique that does not block search engines from accessing your websites.
22
23
24
25	REQUIREMENTS
26
27	You must be:
28	- using a multisite installation
29	- using a separate database for each site (no table prefixing, though the code could be
30	modified to allow for this, patches welcome).
31	- sharing the users table across all sites (If this is not you, what are you hoping that this module
32	will do for you?)
33
34
35
36	INSTALLATION
37
38	1) Install and setup multisite_api before using this module.
39
40	2) Adjust the settings in multisite_api to control which sites are logged in to. Multisite_login
41	will login to all sites that match the current site's visibility and server.
42
43	3) Install and enable this module and multisite_api on all of your sites.
44
45	4) Make sure that you are sharing the user and multisite_login tables on all of your sites. The
46	$db_prefix in the settings.php files of your secondary sites will look something like this:
47
48	$db_prefix = array(
49	'default' => '',
50	'users' => 'master_db.',
51	'multisite_login' => 'master_db.',
52	// You may share other tables here.
53	);
54
55	Note that if you are sharing the sessions table between your sites, then you should also share
56	the multisite_login_sessions table.
57
58	4) Login to one of the sites
59
60	5) If you are an administrator, you will see a string of single-pixel images at the bottom of the
61	page, one for each partner site (If you are not an admin, the images are hidden via CSS techniques). A black image indicates a successfull login, red means failure. Check admin/logs/watchdog on the partner site to see why a login failed.
62
63
64
65	HAVING PROBLEMS?
66
67	1) I get "user/pass does not match" errors.
68
69	Make sure you are sharing the multisite_login table, Review the installation steps above.
70
71	2) I get "The host does not match" errors.
72
73	In rare circumstances, usually only in a development environment, IPs from the same browser
74	session may not in fact match. Go to admin/multisite/multisite_login and disable host matching.
75
76	3) I just copied my database from staging to production and now I can't get one or more sites to
77	work.
78
79	Clear the multisite_api cache on those sites by visiting:
80	admin/multisite/multisite_api
81	And saving the form.
82
83	4) It just doesn't work. My sites are in a subdirectory of the main domain, or are accessed on a
84	special port.
85
86	When Multisite Login creates the URLs that point to the images on the other sites it has to do a
87	bit of guesswork. Normally it will use the name of site directory as the domain of the other
88	site. However this doesn't work if the other site is in a sub-directory, or if the other site
89	uses a non-standard port. In these cases you must set $base_url in your settings.php files, and then go to the multisite api settings page and save the form (this clears the cache).
90
91	5) It works in some browsers / for some of my users, but not others.
92
93	Make sure that the browser is not blocking 3rd party cookies.
94
95	6) I have some other problem.
96
97	1) Install the simpletest module 6.2.x or later.
98	http://drupal.org/project/simpletest
99	2) Run all multisite simpletests
100	3) Report your bug to the Drupal issue queue and attach the results of the simpletest and a
101	screenshot of all watchdog entries created during the simpletest.
102
103
104
105	TECHNIQUE
106
107	When a user logs into a site, the returned html will include several image tags, one for each partner
108	site. The url of the image will include a query string which provides enough information to login the
109	user on the partner site. A cookie belonging to the partner site is then stored on the user's browser.
110	Partner sites return 1x1 images.
111
112	* Originating Site *
113
114	On hook_user $op == login
115	- query each partner site via image tag
116	- img src has a query string that includes: double-munged password, uid, and the session id encoded
117	in a reversable hash
118
119	* Partner Site *
120
121	Via a menu callback
122	- Check if uid/md5 match
123	- Check if IP matches what is stored in the session table for the given session id
124	- Check that the timestamp is recent
125	- Check that this sid hasn't been tried before
126	- log the user in
127	- store the sid so it can't be used again for a multisite login
128	- return image
129	- exit(0);
130
131	* Considerations *
132	We are passing a double MD5ed password, though not theoretically impossible to reverse engineer,
133	if someone really wants to break into your site they would use a method that requires less work.
134	If the query string _were_ to be somehow obtained by a third party, it could not be used by the
135	third party to masquerade as the original user since logins are only allowed once per session id.
136
137
138
139	LOGGING OUT
140
141	Multisite Login does not synchronize logging out accross sites. Consider this scenario: A user
142	logs in to your network of sites. Chances are high that they will spend most of their time on just
143	one site, they might not even vist other sites in the network. Depending on how you have PHP
144	configured, their session will expire on those other sites and they will be automatically logged
145	out, even though they remain logged in on the one site.
146
147	Multiste Login cannot control this situation and so it doesn't make any attempt to do anything when
148	a user explicitly logs out.
149
150	However in theory, if uids were stored in {multisite_login_sessions}, a combination of
151	hook_user $op == 'logout' and hook_cron could be used to log out the user on all sites, patches
152	welcome.
153
154	It is also because of this reason that a user who vists several sites in your network, but at
155	inconsistent frequencies may find that they have to re-login to some sites.
156
157
158
159	CREDITS
160
161	This module was developed by
162
163	Advomatic
164	http://advomatic.com
165
166	and sponsored by
167
168	Politicker
169	http://politicker.com
170	+ 50 state sites
171
172	and
173
174	The New York Observer
175	http://observer.com