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.core.query.sql.model.QueryBuilder;
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    @Override
051    boolean checkUsernamePassword(String username, String password);
052
053    boolean validatePassword(String password);
054
055    /**
056     * Retrieves the principal with the given username or null if it does not exist.
057     * <p>
058     * Can build principals for anonymous and virtual users as well as for users defined in the users directory.
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    NuxeoGroup getGroup(String groupName);
066
067    /**
068     * @deprecated see {@link #searchUsers(String)}
069     */
070    @Deprecated
071    List<NuxeoPrincipal> searchPrincipals(String pattern);
072
073    /**
074     * Search matching groups through their defined search fields
075     *
076     * @since 5.5
077     */
078    DocumentModelList searchGroups(String pattern);
079
080    /**
081     * Returns the list of all user ids.
082     *
083     * @since 5.2M4
084     */
085    List<String> getUserIds();
086
087    /**
088     * Creates user from given model.
089     *
090     * @since 5.2M4
091     * @throws UserAlreadyExistsException
092     */
093    DocumentModel createUser(DocumentModel userModel) throws UserAlreadyExistsException;
094
095    /**
096     * Updates user represented by given model.
097     *
098     * @since 5.2M4
099     */
100    void updateUser(DocumentModel userModel);
101
102    /**
103     * Deletes user represented by given model.
104     *
105     * @since 5.2M4
106     */
107    void deleteUser(DocumentModel userModel);
108
109    /**
110     * Deletes user with given id.
111     *
112     * @since 5.2M4
113     */
114    void deleteUser(String userId);
115
116    /**
117     * Returns a bare user model.
118     * <p>
119     * Can be used for user creation/search screens.
120     *
121     * @since 5.2M4
122     */
123    DocumentModel getBareUserModel();
124
125    /**
126     * Returns the document model representing user with given id or null if it does not exist.
127     *
128     * @since 5.2M4
129     */
130    DocumentModel getUserModel(String userName);
131
132    /**
133     * Returns users matching given pattern
134     * <p>
135     * Pattern is used to fill a filter and fulltext map according to users search fields configuration. Search is
136     * performed on each of these fields (OR).
137     *
138     * @since 5.2M4
139     */
140    DocumentModelList searchUsers(String pattern);
141
142    /**
143     * Returns users matching given criteria.
144     *
145     * @param filter filter with field names as keys
146     * @param fulltext field names used for fulltext match
147     * @since 5.2M4
148     */
149    DocumentModelList searchUsers(Map<String, Serializable> filter, Set<String> fulltext);
150
151    /**
152     * Returns users matching the given query.
153     *
154     * @param queryBuilder the query to use, including limit, offset, ordering and countTotal
155     * @since 10.3
156     */
157    DocumentModelList searchUsers(QueryBuilder queryBuilder);
158
159    String getUserListingMode();
160
161    String getUserSortField();
162
163    Pattern getUserPasswordPattern();
164
165    /**
166     * Returns the list of all groups ids.
167     *
168     * @since 5.2M4
169     */
170    List<String> getGroupIds();
171
172    /**
173     * Returns groups matching given criteria.
174     *
175     * @param filter filter with field names as keys
176     * @param fulltext field names used for fulltext match
177     * @since 5.2M4
178     */
179    DocumentModelList searchGroups(Map<String, Serializable> filter, Set<String> fulltext);
180
181    /**
182     * Returns groups matching the given query.
183     *
184     * @param queryBuilder the query to use, including limit, offset, ordering and countTotal
185     * @since 10.3
186     */
187    DocumentModelList searchGroups(QueryBuilder queryBuilder);
188
189    /**
190     * Creates a group from given model
191     *
192     * @return the created group model
193     * @since 5.2M4
194     * @throws GroupAlreadyExistsException
195     */
196    DocumentModel createGroup(DocumentModel groupModel) throws GroupAlreadyExistsException;
197
198    /**
199     * Updates group represented by given model.
200     *
201     * @since 5.2M4
202     */
203    void updateGroup(DocumentModel groupModel);
204
205    /**
206     * Deletes group represented by given model.
207     *
208     * @since 5.2M4
209     */
210    void deleteGroup(DocumentModel groupModel);
211
212    /**
213     * Deletes group with given id.
214     *
215     * @since 5.2M4
216     */
217    void deleteGroup(String groupId);
218
219    /**
220     * Returns a bare group model.
221     * <p>
222     * Can be used for group creation/search screens.
223     *
224     * @since 5.2M4
225     */
226    DocumentModel getBareGroupModel();
227
228    /**
229     * Return the group document model with this id or null if group does not exist.
230     *
231     * @param groupName the group identifier
232     * @since 5.2M4
233     */
234    DocumentModel getGroupModel(String groupName);
235
236    String getDefaultGroup();
237
238    String getGroupListingMode();
239
240    /**
241     * Returns the list of groups that belong to this group.
242     *
243     * @param parentId the name of the parent group.
244     */
245    List<String> getGroupsInGroup(String parentId);
246
247    /**
248     * Returns the list of groups that are not members of other groups.
249     */
250    List<String> getTopLevelGroups();
251
252    /**
253     * Returns the list of users that belong to this group.
254     *
255     * @param groupId ID of the group
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     */
264    List<String> getUsersInGroupAndSubGroups(String groupId);
265
266    /**
267     * Returns true is users referential is read only (ie : LDAP) -> can not add users -> can not delete users.
268     */
269    Boolean areGroupsReadOnly();
270
271    /**
272     * Returns true is groups referential is read only (ie : LDAP) -> can not add groups -> can not delete groups.
273     */
274    Boolean areUsersReadOnly();
275
276    /**
277     * Gets the user directory name.
278     *
279     * @return the user directory name.
280     */
281    String getUserDirectoryName();
282
283    /**
284     * Returns the user directory schema name.
285     *
286     * @since 5.2M4
287     */
288    String getUserSchemaName();
289
290    /**
291     * Returns the user directory id field.
292     *
293     * @since 5.2M4
294     */
295    String getUserIdField();
296
297    /**
298     * Gets the user email field.
299     *
300     * @return the user email field.
301     */
302    String getUserEmailField();
303
304    /**
305     * Gets the user search fields, the fields to use when a principal search is done.
306     *
307     * @return the search fields.
308     */
309    Set<String> getUserSearchFields();
310
311    /**
312     * Gets the group search fields.
313     */
314    Set<String> getGroupSearchFields();
315
316    /**
317     * Gets the group directory name.
318     *
319     * @return the group directory name.
320     */
321    String getGroupDirectoryName();
322
323    /**
324     * Returns the group directory schema name.
325     *
326     * @since 5.2M4
327     */
328    String getGroupSchemaName();
329
330    /**
331     * Returns the group directory id field.
332     *
333     * @since 5.2M4
334     */
335    String getGroupIdField();
336
337    /**
338     * Returns the group label field.
339     *
340     * @since 5.5
341     */
342    String getGroupLabelField();
343
344    /**
345     * Gets the group members field.
346     *
347     * @return the group members field.
348     */
349    String getGroupMembersField();
350
351    /**
352     * Gets the group sub-groups field.
353     *
354     * @return the sub-groups field.
355     */
356    String getGroupSubGroupsField();
357
358    /**
359     * Gets the group parent-groups field.
360     *
361     * @return the parent-groups field.
362     */
363    String getGroupParentGroupsField();
364
365    /**
366     * Gets the anonymous user id.
367     *
368     * @return the anonymous user id, or the default one if none is defined.
369     */
370    String getAnonymousUserId();
371
372    /** Gets the Digest Auth directory. */
373    String getDigestAuthDirectory();
374
375    /** Gets the Digest Auth realm. */
376    String getDigestAuthRealm();
377
378    /**
379     * Sets the given configuration on the service.
380     *
381     * @param descriptor the descriptor as parsed from xml, merged from the previous one if it exists.
382     */
383    void setConfiguration(UserManagerDescriptor descriptor);
384
385    /**
386     * Returns the list of administrators groups.
387     *
388     * @since 5.3 GA
389     */
390    List<String> getAdministratorsGroups();
391
392    /**
393     * For an ACP, get the list of user that has a permission. This method should be use with care as it can cause
394     * performance issues while getting the list of users.
395     *
396     * @since 5.4.2
397     * @param perm the permission
398     * @param acp The access control policy of the document
399     * @return the list of user ids
400     */
401    String[] getUsersForPermission(String perm, ACP acp);
402
403    /**
404     * Returns the ancestor groups of the group with the given id.
405     *
406     * @since 9.2
407     */
408    List<String> getAncestorGroups(String groupId);
409
410    /**
411     * Returns the contributed {@link GroupConfig}.
412     *
413     * @since 9.3
414     */
415    GroupConfig getGroupConfig();
416
417    /**
418     * Notifies that the given user has changed with the given event:
419     * <ul>
420     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
421     * <li>At the core level, passing the {@code userName} as the {@code "id"} property of the fired event.</li>
422     * </ul>
423     *
424     * @since 9.2
425     */
426    void notifyUserChanged(String userName, String eventId);
427
428    /**
429     * Notifies that the given group has changed with the given event:
430     * <ul>
431     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
432     * <li>At the core level, passing the {@code groupName} as the {@code "id"} property of the fired event.</li>
433     * </ul>
434     *
435     * @since 9.2
436     */
437    default void notifyGroupChanged(String groupName, String eventId) {
438        notifyGroupChanged(groupName, eventId, null);
439    }
440
441    /**
442     * Notifies that the given group has changed with the given event:
443     * <ul>
444     * <li>At the runtime level so that the JaasCacheFlusher listener can make sure the principal cache is reset.</li>
445     * <li>At the core level, passing the {@code groupName} as the {@code "id"} property of the fired event.</li>
446     * </ul>
447     * <p>
448     * The {@code ancestorGroupNames} list must contain the ancestor groups of the given group. It can be computed by
449     * calling {@link #getAncestorGroups(String)}. It will be passed as the {@code "ancestorGroups"} property of the
450     * fired core event.
451     *
452     * @since 9.2
453     */
454    void notifyGroupChanged(String groupName, String eventId, List<String> ancestorGroupNames);
455
456}