You are here

README.txt in Bakery Single Sign-On System 7.3

Same filename and directory in other branches
  1. 6.2 README.txt
  2. 6 README.txt
  3. 7.4 README.txt
  4. 7.2 README.txt
Bakery module, for single sign-on between Drupal sites on the same domain.

In this README:
  * Bakery versions and compatibility
  * Installation and setup
  * How Bakery works
  * Notes on terminology
  * Common problems and support
  * Sharing account information using Bakery
  * Notes on registration/sign-in on subsites
  * Notes on migrating to Bakery
  * Known issues
  * Further information and support

Bakery versions and compatibility:
===========================================
This is the 2.x branch of the Bakery module for Drupal 7. The 2.x branch differs
mainly from the 1.x branch by offering slave site registration and login.

2.x versions between major branches of Drupal are compatible, meaning you can
run a Drupal 7 version of the 2.x branch of Bakery with a Drupal 6 version of
the 2.x branch. 1.x and 2.x branches are not compatible.

Installation and setup:
===========================================
Bakery provides single sign-on (SSO) functionality for two or more sites.
Deploy this module on the authoritative "master" Drupal server and the secondary
"slave" or subsite server. The master and slave must be on the same domain*.

Enable and configure Bakery on the master server first. It is recommended that
you use the UID 1 Drupal account for this configuration.

  1. Enable Bakery at admin/modules
  2. Visit admin/config/system/bakery to configure

This is the master site.

  3. Check the box for "Is this the master site?"
  4. Enter the full URL of this site, including ending forward slash
    - Example: http://example.org/

For SSO to work, Bakery must know the slave, or subsites, to use.

  5. Enter the full URLs of each slave site, separated by newlines
    - Example:  http://store.example.org/
                http://api.example.org/

Two other required fields for Bakery to work are the private key and the cookie
domain.

  6. Enter a long and secure private key
  7. Enter the domain to use for Bakery cookies. These cookies are shared so
      the domain should be the top level, with leading period.
    - Example: .example.org
  8. Save configuration (we'll come back to the other fields)

Now to enable and configure Bakery on the slave or subsite. If possible, you should
log in and use the UID 1 Drupal account for this configuration.

  9. Enable Bakery at admin/modules
  10. Visit admin/config/system/bakery to configure

This is a subsite site.

  11. Do not check the master site box
  12. Enter the full URL of the master site set in step #4
  13. The slave sites textarea can be left blank
  14. Enter the exact same private key set in step #6
  15. Enter the exact same domain set in step #7
  16. Save configuration (we'll come back to the other fields)

Bakery should now be set to work for the master and this slave site. Open a
different browser than the one you are currently using and visit the master
site. Log in with a standard account. Once successful visit the slave site and
confirm that you are also logged in. If you encountered problems at any point
please consult the section here labeled "Problems and support".

You can now enable and configure Bakery for sites in your network if required,
or read the section labeled "Sharing account information using Bakery".

* Master and slave must be on the same domain, but are not required to be at
certain levels. For example, you can have the master be sub.example.com and a
slave be example.com.

How Bakery works:
===========================================
Bakery provides single sign-on between Drupal sites on the same domain using a
shared cookie. When a user authenticates on a site they are sent a cookie by
Drupal, containing a unique identifier for that user. Sub-sequent requests by
that user will contain the identifier, allowing Drupal to recognize that the
request is coming from a specific user, an authenticated user. This process is
handled by Drupal core. Bakery augments the login process and sends an
additional cookie (referred internally to as the CHOCOLATECHIP cookie). Should
the user now visit a sub-site (on the same domain) their browser will send this
Bakery-created cookie. On the sub-site Bakery will recognize the cookie and if
it is valid will authenticate the user (via Drupal core's processes). The user
is now authenticated on both sites while only have to log on to one.

Notes on terminology:
===========================================
Bakery documentation and discussion makes repeated reference to the words
"master" and "slave". The terms stem from the common communication model between
devices or processes in computer systems where one has unidirectional control
over another. In Bakery's case, the master is the site with authoritative
account and authentication information. The master is occasionaly referred to as
the "main" site. The slave site can be referred to as the "subsite", but since
Bakery does not enforce top-level and sub-domains the term "subsite" may be
incorrect for some instances.

Common problems and support:
===========================================
  * Cannot log in, how do I disable Bakery?
    - If you do not have access to disable the Bakery module you'll need 
      access to the Drupal database for the site. To disable Bakery run this
      query: UPDATE system SET status = 0 WHERE name = 'bakery';
      After that you'll also need to clear caches.

Sharing account information using Bakery:
===========================================
A modest amount of account data sharing between Bakery-enabled sites is
supported. The core account fields 'name' and 'mail' are always synchronized.

The following fields from user accounts are optionally synchronized:
  * status
  * user picture
  * language
  * signature
  * timezone

Notes on registration/sign-in on subsites:
===========================================
This feature is important for usability. It's also really easy to configure your
site so that this feature is horrible for usability. A few examples:

Registration:
This feature does not support saving any data other than the username, e-mail 
address, and fields created with the core profile module. If you have other 
modules that modify the registration process to add fields or make the form
behave differently they are unlikely to work properly from the subsite. 

You should keep the "allow registration" and "Require e-mail verification when 
a visitor creates an account" settings the same on all sites. If your
master site disallows registration then no subsites will be allowed to create
accounts either and users will be confused why they see a form but it doesn't
work.

Notes on migrating to Bakery:
===========================================
Migrating to using Bakery can be a fairly simple process. This process will work
for separate sites and for a shared users table, though the latter can require a
few additional steps.

Pre-migration data synchronization is recommended to alleviate potential
account mis-matches. According to Bakery two accounts are in sync when the
username and email are identical and the slave account's init property contains
the URL of the user edit page on the master
(e.g. http://example.org/user/9/edit -- where example.org is the master). The
UID of the accounts do not need to be identical. It is recommended you at least
synchronize usernames and email address for accounts that belong to the same
person across sites.

For people that do not have joint accounts you could ask them via email to
create an account on the site where there account does not exist, to assist the
process.

For accounts that have the same username but different email addresses Bakery
provides a self-service mechanism for synchronizing accounts, but in the event
this is inadequate or confusing you should provide a site administrator contact
mechanism (form or email address) that is easily distinguishable.

In case there are duplicate accounts on one of the sites, the module
http://drupal.org/project/usermerge may help reconcile.

If you have a shared users table solution between sites you will need to remove
that connection before migrating to Bakery. First, populate the other users
tables by synchronizing accounts. Modify settings.php on the shared sites to
remove the table information from the database connection details. If the cookie
domain begins with a leading dot you probably want to remove it, as it could
cause issues when users move between sites.

Once synchronization is complete you can follow the steps listed above on
installation and setup of Baker.

Known issues:
===========================================
  * Values in profile fields exposed on the subsite that are not set on the
    master will not be saved.
  * Bakery is currently incompatible with a configuration that requires
    administrator approval of accounts. An account registered on the slave will
    not be set to blocked on the master.
  * Bakery is not compatible with modules that takeover core Drupal's login and
    registration forms, e.g. ldapprov.

Further information and support:
===========================================
Consult the online documentation at http://drupal.org/node/567410 for more
information.

Please use the public issue queue of Bakery for all bugs and feature requests:
http://drupal.org/project/issues/bakery

File

README.txt
View source
  1. Bakery module, for single sign-on between Drupal sites on the same domain.
  2. In this README:
  3. * Bakery versions and compatibility
  4. * Installation and setup
  5. * How Bakery works
  6. * Notes on terminology
  7. * Common problems and support
  8. * Sharing account information using Bakery
  9. * Notes on registration/sign-in on subsites
  10. * Notes on migrating to Bakery
  11. * Known issues
  12. * Further information and support
  13. Bakery versions and compatibility:
  14. ===========================================
  15. This is the 2.x branch of the Bakery module for Drupal 7. The 2.x branch differs
  16. mainly from the 1.x branch by offering slave site registration and login.
  17. 2.x versions between major branches of Drupal are compatible, meaning you can
  18. run a Drupal 7 version of the 2.x branch of Bakery with a Drupal 6 version of
  19. the 2.x branch. 1.x and 2.x branches are not compatible.
  20. Installation and setup:
  21. ===========================================
  22. Bakery provides single sign-on (SSO) functionality for two or more sites.
  23. Deploy this module on the authoritative "master" Drupal server and the secondary
  24. "slave" or subsite server. The master and slave must be on the same domain*.
  25. Enable and configure Bakery on the master server first. It is recommended that
  26. you use the UID 1 Drupal account for this configuration.
  27. 1. Enable Bakery at admin/modules
  28. 2. Visit admin/config/system/bakery to configure
  29. This is the master site.
  30. 3. Check the box for "Is this the master site?"
  31. 4. Enter the full URL of this site, including ending forward slash
  32. - Example: http://example.org/
  33. For SSO to work, Bakery must know the slave, or subsites, to use.
  34. 5. Enter the full URLs of each slave site, separated by newlines
  35. - Example: http://store.example.org/
  36. http://api.example.org/
  37. Two other required fields for Bakery to work are the private key and the cookie
  38. domain.
  39. 6. Enter a long and secure private key
  40. 7. Enter the domain to use for Bakery cookies. These cookies are shared so
  41. the domain should be the top level, with leading period.
  42. - Example: .example.org
  43. 8. Save configuration (we'll come back to the other fields)
  44. Now to enable and configure Bakery on the slave or subsite. If possible, you should
  45. log in and use the UID 1 Drupal account for this configuration.
  46. 9. Enable Bakery at admin/modules
  47. 10. Visit admin/config/system/bakery to configure
  48. This is a subsite site.
  49. 11. Do not check the master site box
  50. 12. Enter the full URL of the master site set in step #4
  51. 13. The slave sites textarea can be left blank
  52. 14. Enter the exact same private key set in step #6
  53. 15. Enter the exact same domain set in step #7
  54. 16. Save configuration (we'll come back to the other fields)
  55. Bakery should now be set to work for the master and this slave site. Open a
  56. different browser than the one you are currently using and visit the master
  57. site. Log in with a standard account. Once successful visit the slave site and
  58. confirm that you are also logged in. If you encountered problems at any point
  59. please consult the section here labeled "Problems and support".
  60. You can now enable and configure Bakery for sites in your network if required,
  61. or read the section labeled "Sharing account information using Bakery".
  62. * Master and slave must be on the same domain, but are not required to be at
  63. certain levels. For example, you can have the master be sub.example.com and a
  64. slave be example.com.
  65. How Bakery works:
  66. ===========================================
  67. Bakery provides single sign-on between Drupal sites on the same domain using a
  68. shared cookie. When a user authenticates on a site they are sent a cookie by
  69. Drupal, containing a unique identifier for that user. Sub-sequent requests by
  70. that user will contain the identifier, allowing Drupal to recognize that the
  71. request is coming from a specific user, an authenticated user. This process is
  72. handled by Drupal core. Bakery augments the login process and sends an
  73. additional cookie (referred internally to as the CHOCOLATECHIP cookie). Should
  74. the user now visit a sub-site (on the same domain) their browser will send this
  75. Bakery-created cookie. On the sub-site Bakery will recognize the cookie and if
  76. it is valid will authenticate the user (via Drupal core's processes). The user
  77. is now authenticated on both sites while only have to log on to one.
  78. Notes on terminology:
  79. ===========================================
  80. Bakery documentation and discussion makes repeated reference to the words
  81. "master" and "slave". The terms stem from the common communication model between
  82. devices or processes in computer systems where one has unidirectional control
  83. over another. In Bakery's case, the master is the site with authoritative
  84. account and authentication information. The master is occasionaly referred to as
  85. the "main" site. The slave site can be referred to as the "subsite", but since
  86. Bakery does not enforce top-level and sub-domains the term "subsite" may be
  87. incorrect for some instances.
  88. Common problems and support:
  89. ===========================================
  90. * Cannot log in, how do I disable Bakery?
  91. - If you do not have access to disable the Bakery module you'll need
  92. access to the Drupal database for the site. To disable Bakery run this
  93. query: UPDATE system SET status = 0 WHERE name = 'bakery';
  94. After that you'll also need to clear caches.
  95. Sharing account information using Bakery:
  96. ===========================================
  97. A modest amount of account data sharing between Bakery-enabled sites is
  98. supported. The core account fields 'name' and 'mail' are always synchronized.
  99. The following fields from user accounts are optionally synchronized:
  100. * status
  101. * user picture
  102. * language
  103. * signature
  104. * timezone
  105. Notes on registration/sign-in on subsites:
  106. ===========================================
  107. This feature is important for usability. It's also really easy to configure your
  108. site so that this feature is horrible for usability. A few examples:
  109. Registration:
  110. This feature does not support saving any data other than the username, e-mail
  111. address, and fields created with the core profile module. If you have other
  112. modules that modify the registration process to add fields or make the form
  113. behave differently they are unlikely to work properly from the subsite.
  114. You should keep the "allow registration" and "Require e-mail verification when
  115. a visitor creates an account" settings the same on all sites. If your
  116. master site disallows registration then no subsites will be allowed to create
  117. accounts either and users will be confused why they see a form but it doesn't
  118. work.
  119. Notes on migrating to Bakery:
  120. ===========================================
  121. Migrating to using Bakery can be a fairly simple process. This process will work
  122. for separate sites and for a shared users table, though the latter can require a
  123. few additional steps.
  124. Pre-migration data synchronization is recommended to alleviate potential
  125. account mis-matches. According to Bakery two accounts are in sync when the
  126. username and email are identical and the slave account's init property contains
  127. the URL of the user edit page on the master
  128. (e.g. http://example.org/user/9/edit -- where example.org is the master). The
  129. UID of the accounts do not need to be identical. It is recommended you at least
  130. synchronize usernames and email address for accounts that belong to the same
  131. person across sites.
  132. For people that do not have joint accounts you could ask them via email to
  133. create an account on the site where there account does not exist, to assist the
  134. process.
  135. For accounts that have the same username but different email addresses Bakery
  136. provides a self-service mechanism for synchronizing accounts, but in the event
  137. this is inadequate or confusing you should provide a site administrator contact
  138. mechanism (form or email address) that is easily distinguishable.
  139. In case there are duplicate accounts on one of the sites, the module
  140. http://drupal.org/project/usermerge may help reconcile.
  141. If you have a shared users table solution between sites you will need to remove
  142. that connection before migrating to Bakery. First, populate the other users
  143. tables by synchronizing accounts. Modify settings.php on the shared sites to
  144. remove the table information from the database connection details. If the cookie
  145. domain begins with a leading dot you probably want to remove it, as it could
  146. cause issues when users move between sites.
  147. Once synchronization is complete you can follow the steps listed above on
  148. installation and setup of Baker.
  149. Known issues:
  150. ===========================================
  151. * Values in profile fields exposed on the subsite that are not set on the
  152. master will not be saved.
  153. * Bakery is currently incompatible with a configuration that requires
  154. administrator approval of accounts. An account registered on the slave will
  155. not be set to blocked on the master.
  156. * Bakery is not compatible with modules that takeover core Drupal's login and
  157. registration forms, e.g. ldapprov.
  158. Further information and support:
  159. ===========================================
  160. Consult the online documentation at http://drupal.org/node/567410 for more
  161. information.
  162. Please use the public issue queue of Bakery for all bugs and feature requests:
  163. http://drupal.org/project/issues/bakery