Source code

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