001/*
002 * (C) Copyright 2006-20012 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.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 *     Antoine Taillefer
016 */
017package org.nuxeo.ecm.tokenauth.service;
018
019import java.io.Serializable;
020
021import org.nuxeo.ecm.core.api.DocumentModelList;
022import org.nuxeo.ecm.platform.ui.web.auth.token.TokenAuthenticator;
023import org.nuxeo.ecm.tokenauth.TokenAuthenticationException;
024import org.nuxeo.ecm.tokenauth.servlet.TokenAuthenticationServlet;
025
026/**
027 * Service to manage generation and storage of authentication tokens. Each token must be unique and persisted in the
028 * back-end with the user information it is bound to: user name, application name, device name, device description,
029 * permission.
030 * <p>
031 * Typically, the service is called by the {@link TokenAuthenticationServlet} to get a token from the user information
032 * passed as request parameters, and it allows the {@link TokenAuthenticator} to check for a valid identity given a
033 * token passed as a request header.
034 *
035 * @author Antoine Taillefer (ataillefer@nuxeo.com)
036 * @since 5.7
037 */
038public interface TokenAuthenticationService extends Serializable {
039
040    /**
041     * Acquires a unique token for the specified user, application, and device.
042     * <p>
043     * If such a token exist in the back-end for the specified (userName, applicationName, deviceId) triplet, just
044     * returns it, else generates it and stores it in the back-end with the triplet attributes, the specified device
045     * description and permission.
046     *
047     * @throws TokenAuthenticationException if one of the required parameters is null or empty (all parameters are
048     *             required except for the device description)
049     * @throws NuxeoException if multiple tokens are found for the same triplet
050     */
051    String acquireToken(String userName, String applicationName, String deviceId, String deviceDescription,
052            String permission) throws TokenAuthenticationException;
053
054    /**
055     * Gets the token for the specified user, application, and device.
056     *
057     * @return null if such a token doesn't exist
058     * @throws TokenAuthenticationException if one of the required parameters is null or empty (all parameters are
059     *             required except for the device description)
060     * @throws NuxeoException if multiple tokens are found for the same (userName, applicationName, deviceId) triplet
061     */
062    String getToken(String userName, String applicationName, String deviceId) throws TokenAuthenticationException;
063
064    /**
065     * Gets the user name bound to the specified token.
066     *
067     * @return The user name bound to the specified token, or null if the token does not exist in the back-end.
068     */
069    String getUserName(String token);
070
071    /**
072     * Removes the token from the back-end.
073     */
074    void revokeToken(String token);
075
076    /**
077     * Gets the token bindings for the specified user.
078     */
079    DocumentModelList getTokenBindings(String userName);
080
081}