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