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