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 *     Antoine Taillefer
018 */
019package org.nuxeo.ecm.tokenauth.service;
020
021import java.io.Serializable;
022
023import javax.servlet.http.HttpServletRequest;
024
025import org.nuxeo.ecm.core.api.DocumentModelList;
026import org.nuxeo.ecm.platform.ui.web.auth.token.TokenAuthenticator;
027import org.nuxeo.ecm.tokenauth.TokenAuthenticationException;
028import org.nuxeo.ecm.tokenauth.servlet.TokenAuthenticationServlet;
029
030/**
031 * Service to manage generation and storage of authentication tokens. Each token must be unique and persisted in the
032 * back-end with the user information it is bound to: user name, application name, device name, device description,
033 * permission.
034 * <p>
035 * Typically, the service is called by the {@link TokenAuthenticationServlet} to get a token from the user information
036 * passed as request parameters, and it allows the {@link TokenAuthenticator} to check for a valid identity given a
037 * token passed as a request header.
038 *
039 * @author Antoine Taillefer ([email protected])
040 * @since 5.7
041 */
042public interface TokenAuthenticationService extends Serializable {
043
044    /**
045     * Acquires a unique token for the specified user, application, and device.
046     * <p>
047     * If such a token exist in the back-end for the specified (userName, applicationName, deviceId) triplet, just
048     * returns it, else generates it and stores it in the back-end with the triplet attributes, the specified device
049     * description and permission.
050     *
051     * @throws TokenAuthenticationException if one of the required parameters is null or empty (all parameters are
052     *             required except for the device description)
053     * @throws NuxeoException if multiple tokens are found for the same triplet
054     */
055    String acquireToken(String userName, String applicationName, String deviceId, String deviceDescription,
056            String permission) throws TokenAuthenticationException;
057
058    /**
059     * Acquires a unique token for the specified request.
060     * <p>
061     * Parameters needed (applicationName, deviceId, deviceDescription, permission) to acquire the token are extracted
062     * from the request itself.
063     * <p>
064     * If such a token exist in the back-end for the specified (userName, applicationName, deviceId) triplet, just
065     * returns it, else generates it and stores it in the back-end with the triplet attributes, the specified device
066     * description and permission.
067     *
068     * @return a token or null for no principal or for anonymous principal unless 'allowAnonymous' parameter is
069     *         explicitly set to true in the authentication plugin configuration.
070     * @throws TokenAuthenticationException if one of the required parameters is null or empty (all parameters are
071     *             required except for the device description)
072     * @throws NuxeoException if multiple tokens are found for the same triplet
073     * @since 8.3
074     */
075    String acquireToken(HttpServletRequest request) throws TokenAuthenticationException;
076
077    /**
078     * Gets the token for the specified user, application, and device.
079     *
080     * @return null if such a token doesn't exist
081     * @throws TokenAuthenticationException if one of the required parameters is null or empty (all parameters are
082     *             required except for the device description)
083     * @throws NuxeoException if multiple tokens are found for the same (userName, applicationName, deviceId) triplet
084     */
085    String getToken(String userName, String applicationName, String deviceId) throws TokenAuthenticationException;
086
087    /**
088     * Gets the user name bound to the specified token.
089     *
090     * @return The user name bound to the specified token, or null if the token does not exist in the back-end.
091     */
092    String getUserName(String token);
093
094    /**
095     * Removes the token from the back-end.
096     */
097    void revokeToken(String token);
098
099    /**
100     * Gets the token bindings for the specified user.
101     */
102    DocumentModelList getTokenBindings(String userName);
103
104    /**
105     * Gets the token bindings for the specified user and application.
106     * @since 8.3
107     */
108    DocumentModelList getTokenBindings(String userName, String applicationName);
109
110}