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}