Item11180: Fix auto group enrollment.

Clarify documentation and fix bug in Register.pm

git-svn-id: http://svn.foswiki.org/branches/Release01x01@12849 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

core/data/System/AccessControl.txt

@@ -44,6 +44,7 @@ In standard Foswiki a user can create an account in UserRegistration. The follow
    * A confirmation e-mail is sent to the user.
    * A user home page with the WikiName of the user is created in the %USERSWEB% web.
    * The user is added to the %USERSWEB%.%WIKIUSERSTOPIC% topic.
+   * Optionally the user is added to one or more groups.
 
 The default visitor name is %USERSWEB%.WikiGuest. This is the non-authenticated user.  By default the non-authenticated user is not permitted to edit topics.  If you require anonymous editing, see [[UserAuthentication#IndividualScripts]].
 
@@ -62,6 +63,7 @@ By default any member of a group has access rights to both adding and removing u
 
 The =ALLOWTOPICCHANGE= setting defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. This prevents users not in the group from editing the topic to give themselves or others access. For example, for the <nop>KasabianGroup topic write:
    * ==Set <nop>ALLOWTOPICCHANGE = %USERSWEB%.<nop>KasabianGroup==
+      * *Caution* This is set in the "Topic Settings" and not inline in the topic text!
 
 <blockquote class="foswikiHelp">
 %X% Foswiki has strict formatting rules. Make sure you have three spaces, an asterisk, and an extra space in front of any access control rule. See below for more information about ALLOWTOPICCHANGE.

core/data/System/DefaultPreferences.txt

@@ -168,18 +168,23 @@ Preference settings local to your site should be set in [[%LOCALSITEPREFS%]] (th
    * URL for current topic
       * Set TOPICURL = %SCRIPTURL{"view"}%/%BASEWEB%/%BASETOPIC%
 
+#RegistrationOptions
 ---+++ Registration configuration options
 ---++++ Add user to group during registration
    * Group type settings during registration:
-      * =automatic=: users can be automatically added to groups
+      * =automatic=: users will be automatically added to eligible groups
       * =one=: users can select one of the groups
       * =multiple=: users can select from multiple groups to join
       * =none=: user cannot be added to groups while registering
    * Set REGISTRATIONGROUPTYPE = none
-
-   * If REGISTRATIONGROUPS below can be set to a comma separated list of groups, to be shown on the registration topic. 
-   If it is unset, then group change permissions will be used to create the list of groups a user can be added to (for guest driven registration the !RegistrationAgent's permissions are used, for logged in user registration of someone else, that user's permissions are used).
-      * #Set REGISTRATIONGROUPS = 
+
+   * If REGISTRATIONGROUPS is set to a comma separated list of groups, only those listed groups will be shown in the UserRegistration form.
+   If it is unset, then group change permissions will be used to create the list of groups eligible for selection during registration. (When using "self-registration" by guest users, the !RegistrationAgent's permissions are used. If the registration is entered by another logged in user, that user's permissions are used).
+      * #Set REGISTRATIONGROUPS =
+
+   * Implementation Notes:
+      * If the RegistrationAgent or logged in user does not have permission to change one of the listed groups,  then that group will be silently skipped.  The user will not be added to the group.
+      * Group permissions are stored in Topic Settings, *not* inline in the group topic.  Edit the Group Topic Settings to change permissions.
 
 ---+++ Change of Password Message
 

core/data/System/UserAuthentication.txt

@@ -105,6 +105,26 @@ You can customize the default [[%SYSTEMWEB%.UserRegistration]] topic by first co
 A couple of common fields are hidden from normal view to make the registration page as lean as possible. You can unhide those fields on the page by removing =EXCLUDED_= from the =INCLUDE= tags) or add new ones.
 
 New fields may also be added. The =name=""= parameter of the =<input>= tags must start with: ="Fwk0..."= (if this is an optional entry), or ="Fwk1..."= (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
+
+---++++ Automatic Group Membership
+You can also enroll users into groups during registration. Options include:
+   * Automatically enrolling users in one or more groups during registration
+   * Allow the user to select multiple groups from a list of eligible groups
+   * Allow the user to choose only _one_ group from a list of eligible groups
+   * Don't do any group enrollment during registration.
+
+The list of eligible groups can be generated in one of two ways:
+   * Manually by configuration.  This fixed list of groups will always be listed.
+   * Automatically based upon CHANGE permission on the group topics.
+
+There are two registration scenarios that apply:
+
+   $ Self-registration by Guest users:  The actual registration will be processed by the special internal user %USERSWEB%.RegistrationAgent.  Group topics must include an ALLOWTOPICCHANGE = %USERSWEB%.RegistrationAgent to be eligible for enrollment.
+   $ Registration by logged-in users:  The registration form is filled out by some other logged-in user.  In this case, the %USERSWEB%.RegistrationAgent is *not* used for Group updates.  The current user must have ALLOWTOPICCHANGE permission for groups for them to be eligible for enrollment.
+
+Note: During registration, if it turns out that the current user or %USERSWEB%.RegistrationAgent doesn't have permission to update the group topic, the group update will be silently skipped.  The user will still be albe to register.
+
+See DefaultPreferences#RegistrationOptions for further details.  Copy the settings into %USERSWEB%.SitePreferences to make them active.
 %ENDSECTION{"TemplateLogin"}%
 
 #ApacheLogin

core/lib/Foswiki/UI/Register.pm

@@ -875,6 +875,7 @@ sub _complete {
             $session->{user} =
               $session->{users}->getCanonicalUserID(
                 $Foswiki::cfg{Register}{RegistrationAgentWikiName} );
+            $regoAgent = $session->{user};
 
             # SECURITY ISSUE:
             # When upgrading an existing Wiki, the RegistrationUser is