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