001/*
002 * (C) Copyright 2006-2016 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     Nuxeo - initial API and implementation
018 */
019package org.nuxeo.ecm.platform.usermanager;
020
021import java.io.Serializable;
022import java.util.List;
023import java.util.Map;
024import java.util.Set;
025import java.util.regex.Pattern;
026
027import org.nuxeo.ecm.core.api.DocumentModel;
028import org.nuxeo.ecm.core.api.DocumentModelList;
029import org.nuxeo.ecm.core.api.NuxeoGroup;
030import org.nuxeo.ecm.core.api.NuxeoPrincipal;
031import org.nuxeo.ecm.core.api.security.ACP;
032import org.nuxeo.ecm.directory.DirectoryException;
033import org.nuxeo.ecm.platform.usermanager.exceptions.GroupAlreadyExistsException;
034import org.nuxeo.ecm.platform.usermanager.exceptions.UserAlreadyExistsException;
035import org.nuxeo.runtime.api.login.Authenticator;
036import org.nuxeo.runtime.services.event.EventListener;
037
038/**
039 * @author Anahide Tchertchian
040 * @author Sun Seng David TAN <stan@nuxeo.com>
041 * @author Benjamin Jalon <bjalon@nuxeo.com>
042 */
043public interface UserManager extends Authenticator, EventListener, Serializable {
044
045    enum MatchType {
046        EXACT, SUBSTRING
047    }
048
049    @Override
050    boolean checkUsernamePassword(String username, String password);
051
052    boolean validatePassword(String password);
053
054    /**
055     * Retrieves the principal with the given username or null if it does not exist.
056     * <p>
057     * Can build principals for anonymous and virtual users as well as for users defined in the users directory.
058     */
059    NuxeoPrincipal getPrincipal(String username);
060
061    /**
062     * Returns the nuxeo group with given name or null if it does not exist.
063     */
064    NuxeoGroup getGroup(String groupName);
065
066    /**
067     * @deprecated see {@link #searchUsers(String)}
068     */
069    @Deprecated
070    List<NuxeoPrincipal> searchPrincipals(String pattern);
071
072    /**
073     * Search matching groups through their defined search fields
074     *
075     * @since 5.5
076     */
077    DocumentModelList searchGroups(String pattern);
078
079    /**
080     * Returns the list of all user ids.
081     *
082     * @since 5.2M4
083     */
084    List<String> getUserIds();
085
086    /**
087     * Creates user from given model.
088     *
089     * @since 5.2M4
090     * @throws UserAlreadyExistsException
091     */
092    DocumentModel createUser(DocumentModel userModel) throws UserAlreadyExistsException;
093
094    /**
095     * Updates user represented by given model.
096     *
097     * @since 5.2M4
098     */
099    void updateUser(DocumentModel userModel);
100
101    /**
102     * Deletes user represented by given model.
103     *
104     * @since 5.2M4
105     * @throws DirectoryException if given entry does not exist
106     */
107    void deleteUser(DocumentModel userModel);
108
109    /**
110     * Deletes user with given id.
111     *
112     * @since 5.2M4
113     * @throws DirectoryException if given entry does not exist
114     */
115    void deleteUser(String userId);
116
117    /**
118     * Returns a bare user model.
119     * <p>
120     * Can be used for user creation/search screens.
121     *
122     * @since 5.2M4
123     */
124    DocumentModel getBareUserModel();
125
126    /**
127     * Returns the document model representing user with given id or null if it does not exist.
128     *
129     * @since 5.2M4
130     */
131    DocumentModel getUserModel(String userName);
132
133    /**
134     * Returns users matching given pattern
135     * <p>
136     * Pattern is used to fill a filter and fulltext map according to users search fields configuration. Search is
137     * performed on each of these fields (OR).
138     *
139     * @since 5.2M4
140     */
141    DocumentModelList searchUsers(String pattern);
142
143    /**
144     * Returns users matching given criteria.
145     *
146     * @param filter filter with field names as keys
147     * @param fulltext field names used for fulltext match
148     * @since 5.2M4
149     */
150    DocumentModelList searchUsers(Map<String, Serializable> filter, Set<String> fulltext);
151
152    String getUserListingMode();
153
154    String getUserSortField();
155
156    Pattern getUserPasswordPattern();
157
158    /**
159     * Returns the list of all groups ids.
160     *
161     * @since 5.2M4
162     */
163    List<String> getGroupIds();
164
165    /**
166     * Returns groups matching given criteria.
167     *
168     * @param filter filter with field names as keys
169     * @param fulltext field names used for fulltext match
170     * @since 5.2M4
171     */
172    DocumentModelList searchGroups(Map<String, Serializable> filter, Set<String> fulltext);
173
174    /**
175     * Creates a group from given model
176     *
177     * @return the created group model
178     * @since 5.2M4
179     * @throws GroupAlreadyExistsException
180     */
181    DocumentModel createGroup(DocumentModel groupModel) throws GroupAlreadyExistsException;
182
183    /**
184     * Updates group represented by given model.
185     *
186     * @since 5.2M4
187     * @throws DirectoryException if given entry does not exist
188     */
189    void updateGroup(DocumentModel groupModel);
190
191    /**
192     * Deletes group represented by given model.
193     *
194     * @since 5.2M4
195     * @throws DirectoryException if given entry does not exist
196     */
197    void deleteGroup(DocumentModel groupModel);
198
199    /**
200     * Deletes group with given id.
201     *
202     * @since 5.2M4
203     * @throws DirectoryException if given entry does not exist
204     */
205    void deleteGroup(String groupId);
206
207    /**
208     * Returns a bare group model.
209     * <p>
210     * Can be used for group creation/search screens.
211     *
212     * @since 5.2M4
213     */
214    DocumentModel getBareGroupModel();
215
216    /**
217     * Return the group document model with this id or null if group does not exist.
218     *
219     * @param groupName the group identifier
220     * @since 5.2M4
221     */
222    DocumentModel getGroupModel(String groupName);
223
224    String getDefaultGroup();
225
226    String getGroupListingMode();
227
228    /**
229     * Returns the list of groups that belong to this group.
230     *
231     * @param parentId the name of the parent group.
232     */
233    List<String> getGroupsInGroup(String parentId);
234
235    /**
236     * Returns the list of groups that are not members of other groups.
237     */
238    List<String> getTopLevelGroups();
239
240    /**
241     * Returns the list of users that belong to this group.
242     *
243     * @param groupId ID of the group
244     */
245    List<String> getUsersInGroup(String groupId);
246
247    /**
248     * Get users from a group and its subgroups.
249     *
250     * @param groupId ID of the group
251     */
252    List<String> getUsersInGroupAndSubGroups(String groupId);
253
254    /**
255     * Returns true is users referential is read only (ie : LDAP) -> can not add users -> can not delete users.
256     */
257    Boolean areGroupsReadOnly();
258
259    /**
260     * Returns true is groups referential is read only (ie : LDAP) -> can not add groups -> can not delete groups.
261     */
262    Boolean areUsersReadOnly();
263
264    /**
265     * Gets the user directory name.
266     *
267     * @return the user directory name.
268     */
269    String getUserDirectoryName();
270
271    /**
272     * Returns the user directory schema name.
273     *
274     * @since 5.2M4
275     */
276    String getUserSchemaName();
277
278    /**
279     * Returns the user directory id field.
280     *
281     * @since 5.2M4
282     */
283    String getUserIdField();
284
285    /**
286     * Gets the user email field.
287     *
288     * @return the user email field.
289     */
290    String getUserEmailField();
291
292    /**
293     * Gets the user search fields, the fields to use when a principal search is done.
294     *
295     * @return the search fields.
296     */
297    Set<String> getUserSearchFields();
298
299    /**
300     * Gets the group search fields.
301     */
302    Set<String> getGroupSearchFields();
303
304    /**
305     * Gets the group directory name.
306     *
307     * @return the group directory name.
308     */
309    String getGroupDirectoryName();
310
311    /**
312     * Returns the group directory schema name.
313     *
314     * @since 5.2M4
315     */
316    String getGroupSchemaName();
317
318    /**
319     * Returns the group directory id field.
320     *
321     * @since 5.2M4
322     */
323    String getGroupIdField();
324
325    /**
326     * Returns the group label field.
327     *
328     * @since 5.5
329     */
330    String getGroupLabelField();
331
332    /**
333     * Gets the group members field.
334     *
335     * @return the group members field.
336     */
337    String getGroupMembersField();
338
339    /**
340     * Gets the group sub-groups field.
341     *
342     * @return the sub-groups field.
343     */
344    String getGroupSubGroupsField();
345
346    /**
347     * Gets the group parent-groups field.
348     *
349     * @return the parent-groups field.
350     */
351    String getGroupParentGroupsField();
352
353    /**
354     * Gets the anonymous user id.
355     *
356     * @return the anonymous user id, or the default one if none is defined.
357     */
358    String getAnonymousUserId();
359
360    /** Gets the Digest Auth directory. */
361    String getDigestAuthDirectory();
362
363    /** Gets the Digest Auth realm. */
364    String getDigestAuthRealm();
365
366    /**
367     * Sets the given configuration on the service.
368     *
369     * @param descriptor the descriptor as parsed from xml, merged from the previous one if it exists.
370     */
371    void setConfiguration(UserManagerDescriptor descriptor);
372
373    /**
374     * Returns the list of administrators groups.
375     *
376     * @since 5.3 GA
377     */
378    List<String> getAdministratorsGroups();
379
380    /**
381     * For an ACP, get the list of user that has a permission. This method should be use with care as it can cause
382     * performance issues while getting the list of users.
383     *
384     * @since 5.4.2
385     * @param perm the permission
386     * @param acp The access control policy of the document
387     * @return the list of user ids
388     */
389    String[] getUsersForPermission(String perm, ACP acp);
390
391    /**
392     * Returns the ancestor groups of the group with the given id.
393     *
394     * @since 9.2
395     */
396    List<String> getAncestorGroups(String groupId);
397
398    /**
399     * Returns the contributed {@link GroupConfig}.
400     *
401     * @since 9.3
402     */
403    GroupConfig getGroupConfig();
404
405    /**
406     * Notifies that the given user has changed with the given event:
407     * <ul>
408     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
409     * <li>At the core level, passing the {@code userName} as the {@code "id"} property of the fired event.</li>
410     * </ul>
411     *
412     * @since 9.2
413     */
414    void notifyUserChanged(String userName, String eventId);
415
416    /**
417     * Notifies that the given group has changed with the given event:
418     * <ul>
419     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
420     * <li>At the core level, passing the {@code groupName} as the {@code "id"} property of the fired event.</li>
421     * </ul>
422     *
423     * @since 9.2
424     */
425    default void notifyGroupChanged(String groupName, String eventId) {
426        notifyGroupChanged(groupName, eventId, null);
427    }
428
429    /**
430     * Notifies that the given group has changed with the given event:
431     * <ul>
432     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
433     * <li>At the core level, passing the {@code groupName} as the {@code "id"} property of the fired event.</li>
434     * </ul>
435     * <p>
436     * The {@code ancestorGroupNames} list must contain the ancestor groups of the given group. It can be computed by
437     * calling {@link #getAncestorGroups(String)}. It will be passed as the {@code "ancestorGroups"} property of the
438     * fired core event.
439     *
440     * @since 9.2
441     */
442    void notifyGroupChanged(String groupName, String eventId, List<String> ancestorGroupNames);
443
444}