001/* 
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.  
018 */
019package org.apache.wiki.auth.authorize;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.core.Session;
023import org.apache.wiki.api.engine.Initializable;
024import org.apache.wiki.auth.AuthorizationManager;
025import org.apache.wiki.auth.Authorizer;
026import org.apache.wiki.auth.NoSuchPrincipalException;
027import org.apache.wiki.auth.WikiSecurityException;
028import org.apache.wiki.auth.permissions.AllPermission;
029import org.apache.wiki.event.WikiEventListener;
030import org.apache.wiki.event.WikiEventManager;
031
032import jakarta.servlet.http.HttpServletRequest;
033import org.apache.wiki.event.WikiSecurityEvent;
034import org.apache.wiki.security.EventUtil;
035import org.apache.wiki.ui.Installer;
036
037
038/**
039 * <p>
040 * Facade class for storing, retrieving and managing wiki groups on behalf of AuthorizationManager, JSPs and other presentation-layer
041 * classes. GroupManager works in collaboration with a back-end {@link GroupDatabase}, which persists groups to permanent storage.
042 * </p>
043 * <p>
044 * <em>Note: prior to JSPWiki 2.4.19, GroupManager was an interface; it is now a concrete, final class. The aspects of GroupManager
045 * which previously extracted group information from storage (e.g., wiki pages) have been refactored into the GroupDatabase interface.</em>
046 * </p>
047 * @since 2.4.19
048 */
049public interface GroupManager extends Initializable, Authorizer, WikiEventListener {
050
051    /** Key used for adding UI messages to a user's Session. */
052    String MESSAGES_KEY = "group";
053
054    String PROP_GROUPDATABASE = "jspwiki.groupdatabase";
055
056    /**
057     * Returns the Group matching a given name. If the group cannot be found, this method throws a <code>NoSuchPrincipalException</code>.
058     *
059     * @param name the name of the group to find
060     * @return the group
061     * @throws NoSuchPrincipalException if the group cannot be found
062     */
063    Group getGroup( final String name ) throws NoSuchPrincipalException;
064
065    /**
066     * Returns the current external {@link GroupDatabase} in use. This method is guaranteed to return a properly-initialized GroupDatabase,
067     * unless it could not be initialized. In that case, this method throws a {@link org.apache.wiki.api.exceptions.WikiException}. The
068     * GroupDatabase is lazily initialized.
069     *
070     * @throws org.apache.wiki.auth.WikiSecurityException if the GroupDatabase could not be initialized
071     * @return the current GroupDatabase
072     * @since 2.3
073     */
074    GroupDatabase getGroupDatabase() throws WikiSecurityException;
075
076    /**
077     * <p>
078     * Extracts group name and members from passed parameters and populates an existing Group with them. The Group will either be a copy of
079     * an existing Group (if one can be found), or a new, unregistered Group (if not). Optionally, this method can throw a
080     * WikiSecurityException if the Group does not yet exist in the GroupManager cache.
081     * </p>
082     * <p>
083     * The <code>group</code> parameter in the HTTP request contains the Group name to look up and populate. The <code>members</code>
084     * parameter contains the member list. If these differ from those in the existing group, the passed values override the old values.
085     * </p>
086     * <p>
087     * This method does not commit the new Group to the GroupManager cache. To do that, use {@link #setGroup(Session, Group)}.
088     * </p>
089     * @param name the name of the group to construct
090     * @param memberLine the line of text containing the group membership list
091     * @param create whether this method should create a new, empty Group if one with the requested name is not found. If <code>false</code>,
092     *            groups that do not exist will cause a <code>NoSuchPrincipalException</code> to be thrown
093     * @return a new, populated group
094     * @see org.apache.wiki.auth.authorize.Group#RESTRICTED_GROUPNAMES
095     * @throws WikiSecurityException if the group name isn't allowed, or if <code>create</code> is <code>false</code>
096     *                               and the Group named <code>name</code> does not exist
097     */
098    Group parseGroup( String name, String memberLine, boolean create ) throws WikiSecurityException;
099
100    /**
101     * <p>
102     * Extracts group name and members from the HTTP request and populates an existing Group with them. The Group will either be a copy of
103     * an existing Group (if one can be found), or a new, unregistered Group (if not). Optionally, this method can throw a
104     * WikiSecurityException if the Group does not yet exist in the GroupManager cache.
105     * </p>
106     * <p>
107     * The <code>group</code> parameter in the HTTP request contains the Group name to look up and populate. The <code>members</code>
108     * parameter contains the member list. If these differ from those in the existing group, the passed values override the old values.
109     * </p>
110     * <p>
111     * This method does not commit the new Group to the GroupManager cache. To do that, use {@link #setGroup(Session, Group)}.
112     * </p>
113     * @param context the current wiki context
114     * @param create whether this method should create a new, empty Group if one with the requested name is not found. If <code>false</code>,
115     *            groups that do not exist will cause a <code>NoSuchPrincipalException</code> to be thrown
116     * @return a new, populated group
117     * @throws WikiSecurityException if the group name isn't allowed, if the group is the Admin group and the current session does not have
118     *                               AllPermission, or if <code>create</code> is <code>false</code> and the Group does not exist
119     */
120    default Group parseGroup( final Context context, final boolean create ) throws WikiSecurityException {
121        // Extract parameters
122        final HttpServletRequest request = context.getHttpRequest();
123        final String name = request.getParameter( "group" );
124        final String memberLine = request.getParameter( "members" );
125
126        // The default policy grants AllPermission to the Admin group, so a page creates it only for a session that has that permission.
127        // The installer creates the group with the parseGroup that takes the name, so it is not affected.
128        if( create && Installer.ADMIN_GROUP.equals( name ) && !context.getEngine().getManager( AuthorizationManager.class )
129                .checkPermission( context.getWikiSession(), new AllPermission( context.getEngine().getApplicationName() ) ) ) {
130            throw new WikiSecurityException( "Illegal group name: " + name );
131        }
132
133        // Create the named group; we pass on any NoSuchPrincipalExceptions
134        // that may be thrown if create == false, or WikiSecurityExceptions
135        final Group group = parseGroup( name, memberLine, create );
136
137        // If no members, add the current user by default
138        if( group.members().length == 0 ) {
139            group.add( context.getWikiSession().getUserPrincipal() );
140        }
141
142        return group;
143    }
144
145    /**
146     * Removes a named Group from the group database. If not found, throws a <code>NoSuchPrincipalException</code>. After removal, this
147     * method will commit the delete to the back-end group database. It will also fire a
148     * {@link org.apache.wiki.event.WikiSecurityEvent#GROUP_REMOVE} event with the GroupManager instance as the source and the Group as target.
149     * If <code>index</code> is <code>null</code>, this method throws an {@link IllegalArgumentException}.
150     *
151     * @param index the group to remove
152     * @throws WikiSecurityException if the Group cannot be removed by the back-end, or if it is the <code>Admin</code> group
153     * @see org.apache.wiki.auth.authorize.GroupDatabase#delete(Group)
154     */
155    void removeGroup( final String index ) throws WikiSecurityException;
156
157    /**
158     * <p>
159     * Saves the {@link Group} created by a user in a wiki session. This method registers the Group with the GroupManager and saves it to
160     * the back-end database. If an existing Group with the same name already exists, the new group will overwrite it. After saving the
161     * Group, the group database changes are committed.
162     * </p>
163     * <p>
164     * This method fires the following events:
165     * </p>
166     * <ul>
167     * <li><strong>When creating a new Group</strong>, this method fires a {@link org.apache.wiki.event.WikiSecurityEvent#GROUP_ADD} with
168     * the GroupManager instance as its source and the new Group as the target.</li>
169     * <li><strong>When overwriting an existing Group</strong>, this method fires a new
170     * {@link org.apache.wiki.event.WikiSecurityEvent#GROUP_REMOVE} with this GroupManager instance as the source, and the new Group as the
171     * target. It then fires a {@link org.apache.wiki.event.WikiSecurityEvent#GROUP_ADD} event with the same source and target.</li>
172     * </ul>
173     * <p>
174     * In addition, if the save or commit actions fail, this method will attempt to restore the older version of the wiki group if it
175     * exists. This will result in a <code>GROUP_REMOVE</code> event (for the new version of the Group) followed by a <code>GROUP_ADD</code>
176     * event (to indicate restoration of the old version).
177     * </p>
178     * <p>
179     * This method will register the new Group with the GroupManager. For example, {@link org.apache.wiki.auth.AuthenticationManager}
180     * attaches each Session as a GroupManager listener. Thus, the act of registering a Group with <code>setGroup</code> means that
181     * all Sessions will automatically receive group add/change/delete events immediately.
182     * </p>
183     *
184     * @param session the wiki session, which may not be <code>null</code>
185     * @param group the Group, which may not be <code>null</code>
186     * @throws WikiSecurityException if the Group cannot be saved by the back-end
187     */
188    void setGroup( final Session session, final Group group ) throws WikiSecurityException;
189
190    /**
191     * Validates a Group, and appends any errors to the session errors list. Any validation errors are added to the wiki session's messages
192     * collection (see {@link Session#getMessages()}.
193     *
194     * @param context the current wiki context
195     * @param group the supplied Group
196     */
197    void validateGroup( final Context context, final Group group );
198
199    /**
200     * Checks if a String is blank or a restricted Group name, and if it is, appends an error to the Session's message list.
201     *
202     * @param context the wiki context
203     * @param name the Group name to test
204     * @throws WikiSecurityException if <code>session</code> is <code>null</code> or the Group name is illegal
205     * @see Group#RESTRICTED_GROUPNAMES
206     */
207    void checkGroupName( final Context context, final String name ) throws WikiSecurityException;
208
209    // events processing .......................................................
210
211    /**
212     * Registers a WikiEventListener with this instance. This is a convenience method.
213     *
214     * @param listener the event listener
215     */
216    void addWikiEventListener( WikiEventListener listener );
217
218    /**
219     * Un-registers a WikiEventListener with this instance. This is a convenience method.
220     *
221     * @param listener the event listener
222     */
223    void removeWikiEventListener( WikiEventListener listener );
224
225    /**
226     *  Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
227     *
228     * @see org.apache.wiki.event.WikiSecurityEvent
229     * @param type       the event type to be fired
230     * @param target     the changed Object, which may be <code>null</code>
231     */
232    default void fireEvent( final int type, final Object target ) {
233        if( WikiEventManager.isListening( this ) ) {
234            WikiEventManager.fireEvent( this, 
235                    EventUtil.applyFrom(new WikiSecurityEvent( this, type, target ) ) );
236        }
237    }
238
239}