001/*
002 * (C) Copyright 2006-2015 Nuxeo SA (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-2.1.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 */
018
019package org.nuxeo.usermapper.service;
020
021import java.io.Serializable;
022import java.util.Map;
023import java.util.Set;
024
025import org.nuxeo.ecm.core.api.NuxeoException;
026import org.nuxeo.ecm.core.api.NuxeoPrincipal;
027import org.nuxeo.usermapper.extension.UserMapper;
028
029/**
030 * This service allows to map Nuxeo Users with users coming from external system like SSO or IDM.
031 *
032 * @author tiry
033 * @since 7.4
034 */
035public interface UserMapperService {
036
037    /**
038     * Should retrieve (create if needed) and update the NuxeoPrincipal according to the given userObject
039     *
040     * @param mappingName the name of the contributed mapping to use
041     * @param userObject the native userObject
042     * @return the matching {@link NuxeoPrincipal}
043     * @throws NuxeoException
044     */
045    NuxeoPrincipal getOrCreateAndUpdateNuxeoPrincipal(String mappingName, Object userObject) throws NuxeoException;
046
047    /**
048     * Should retrieve (create if needed) and update the NuxeoPrincipal according to the given userObject
049     *
050     * @param mappingName the name of the contributed mapping to use
051     * @param userObject the native userObject
052     * @param createIfNeeded flag to allow creation (default is true)
053     * @param update flag to run update (default is true)
054     * @return the matching {@link NuxeoPrincipal}
055     * @throws NuxeoException
056     */
057    NuxeoPrincipal getOrCreateAndUpdateNuxeoPrincipal(String mappingName, Object userObject, boolean createIfNeeded,
058            boolean update, Map<String, Serializable> params) throws NuxeoException;
059
060    /**
061     * Wrap the {@link NuxeoPrincipal} as the userObject used in the external authentication system *
062     *
063     * @param mappingName the name of the contributed mapping to use
064     * @param principal the {@link NuxeoPrincipal} to wrap
065     * @param nativePrincipal the principal Object in the target system (can be null)
066     * @throws NuxeoException
067     */
068    Object wrapNuxeoPrincipal(String mappingName, NuxeoPrincipal principal, Object nativePrincipal,
069            Map<String, Serializable> params) throws NuxeoException;
070
071    /**
072     * Gives access to the contributed Mapping names
073     */
074    Set<String> getAvailableMappings();
075
076    /**
077     * returns the named mapper is any
078     *
079     * @param mappingName
080     */
081    UserMapper getMapper(String mappingName) throws NuxeoException;
082}