    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.auth;
    020
    021import org.apache.wiki.api.core.Session;
    022import org.apache.wiki.api.engine.Initializable;
    023import org.apache.wiki.auth.authorize.Role;
    024import org.apache.wiki.event.WikiEventListener;
    025import org.apache.wiki.event.WikiEventManager;
    026import org.apache.wiki.event.WikiSecurityEvent;
    027
    028import javax.security.auth.Subject;
    029import javax.security.auth.callback.CallbackHandler;
    030import javax.security.auth.spi.LoginModule;
    031import javax.servlet.http.HttpServletRequest;
    032import java.security.Principal;
    033import java.util.Map;
    034import java.util.Set;
    035
    036
    037/**
    038 * Manages authentication activities for a Engine: user login, logout, and credential refreshes. This class uses JAAS to determine how
    039 * users log in.
    040 * <p>
    041 * The login procedure is protected in addition by a mechanism which prevents a hacker to try and force-guess passwords by slowing down
    042 * attempts to log in into the same account.  Every login attempt is recorded, and stored for a while (currently ten minutes), and each
    043 * login attempt during that time incurs a penalty of 2^login attempts milliseconds - that is, 10 login attempts incur a login penalty
    044 * of 1.024 seconds. The delay is currently capped to 20 seconds.
    045 *
    046 * @since 2.3
    047 */
    048public interface AuthenticationManager extends Initializable {
    049
    050    /** If this jspwiki.properties property is <code>true</code>, logs the IP address of the editor on saving. */
    051    String PROP_STOREIPADDRESS = "jspwiki.storeIPAddress";
    052
    053    /** If this jspwiki.properties property is <code>true</code>, allow cookies to be used for authentication. */
    054    String PROP_ALLOW_COOKIE_AUTH = "jspwiki.cookieAuthentication";
    055
    056    /** Whether logins should be throttled to limit brute-forcing attempts. Defaults to true. */
    057    String PROP_LOGIN_THROTTLING = "jspwiki.login.throttling";
    058
    059    /** Prefix for LoginModule options key/value pairs. */
    060    String PREFIX_LOGIN_MODULE_OPTIONS = "jspwiki.loginModule.options.";
    061
    062    /** If this jspwiki.properties property is <code>true</code>, allow cookies to be used to assert identities. */
    063    String PROP_ALLOW_COOKIE_ASSERTIONS = "jspwiki.cookieAssertions";
    064
    065    /** The {@link LoginModule} to use for custom authentication. */
    066    String PROP_LOGIN_MODULE = "jspwiki.loginModule.class";
    067
    068    /**
    069     * Returns true if this Engine uses container-managed authentication. This method is used primarily for cosmetic purposes in the
    070     * JSP tier, and performs no meaningful security function per se. Delegates to
    071     * {@link org.apache.wiki.auth.authorize.WebContainerAuthorizer#isContainerAuthorized()},
    072     * if used as the external authorizer; otherwise, returns <code>false</code>.
    073     *
    074     * @return <code>true</code> if the wiki's authentication is managed by the container, <code>false</code> otherwise
    075     */
    076    boolean isContainerAuthenticated();
    077
    078    /**
    079     * <p>Logs in the user by attempting to populate a Session Subject from a web servlet request by examining the request
    080     *  for the presence of container credentials and user cookies. The processing logic is as follows:
    081     * </p>
    082     * <ul>
    083     * <li>If the Session had previously been unauthenticated, check to see if user has subsequently authenticated. To be considered
    084     * "authenticated," the request must supply one of the following (in order of preference): the container <code>userPrincipal</code>,
    085     * container <code>remoteUser</code>, or authentication cookie. If the user is authenticated, this method fires event
    086     * {@link org.apache.wiki.event.WikiSecurityEvent#LOGIN_AUTHENTICATED} with two parameters: a Principal representing the login principal,
    087     * and the current Session. In addition, if the authorizer is of type WebContainerAuthorizer, this method iterates through the
    088     * container roles returned by {@link org.apache.wiki.auth.authorize.WebContainerAuthorizer#getRoles()}, tests for membership in each
    089     * one, and adds those that pass to the Subject's principal set.</li>
    090     * <li>If, after checking for authentication, the Session is still Anonymous, this method next checks to see if the user has
    091     * "asserted" an identity by supplying an assertion cookie. If the user is found to be asserted, this method fires event
    092     * {@link org.apache.wiki.event.WikiSecurityEvent#LOGIN_ASSERTED} with two parameters: <code>WikiPrincipal(<em>cookievalue</em>)</code>,
    093     * and the current Session.</li>
    094     * <li>If, after checking for authenticated and asserted status, the  Session is <em>still</em> anonymous, this method fires event
    095     * {@link org.apache.wiki.event.WikiSecurityEvent#LOGIN_ANONYMOUS} with two parameters: <code>WikiPrincipal(<em>remoteAddress</em>)</code>,
    096     * and the current Session </li>
    097     * </ul>
    098     *
    099     * @param request servlet request for this user
    100     * @return always returns <code>true</code> (because anonymous login, at least, will always succeed)
    101     * @throws org.apache.wiki.auth.WikiSecurityException if the user cannot be logged in for any reason
    102     * @since 2.3
    103     */
    104    boolean login( HttpServletRequest request ) throws WikiSecurityException;
    105
    106    /**
    107     * Attempts to perform a Session login for the given username/password combination using JSPWiki's custom authentication mode. In
    108     * order to log in, the JAAS LoginModule supplied by the Engine property {@link #PROP_LOGIN_MODULE} will be instantiated, and its
    109     * {@link javax.security.auth.spi.LoginModule#initialize(Subject, CallbackHandler, Map, Map)} method will be invoked. By default,
    110     * the {@link org.apache.wiki.auth.login.UserDatabaseLoginModule} class will be used. When the LoginModule's <code>initialize</code>
    111     * method is invoked, an options Map populated by properties keys prefixed by {@link #PREFIX_LOGIN_MODULE_OPTIONS} will be passed as a
    112     * parameter.
    113     *
    114     * @param session the current wiki session; may not be <code>null</code>.
    115     * @param request the user's HTTP request. This parameter may be <code>null</code>, but the configured LoginModule will not have access
    116     *                to the HTTP request in this case.
    117     * @param username The user name. This is a login name, not a WikiName. In most cases they are the same, but in some cases, they might not be.
    118     * @param password the password
    119     * @return true, if the username/password is valid
    120     * @throws org.apache.wiki.auth.WikiSecurityException if the Authorizer or UserManager cannot be obtained
    121     */
    122    boolean login( Session session, HttpServletRequest request, String username, String password ) throws WikiSecurityException;
    123
    124    /**
    125     * Logs the user out by retrieving the Session associated with the HttpServletRequest and unbinding all of the Subject's Principals,
    126     * except for {@link Role#ALL}, {@link Role#ANONYMOUS}. is a cheap-and-cheerful way to do it without invoking JAAS LoginModules.
    127     * The logout operation will also flush the JSESSIONID cookie from the user's browser session, if it was set.
    128     *
    129     * @param request the current HTTP request
    130     */
    131    void logout( HttpServletRequest request );
    132
    133    /**
    134     * Determines whether this Engine allows users to assert identities using cookies instead of passwords. This is determined by inspecting
    135     * the Engine property {@link #PROP_ALLOW_COOKIE_ASSERTIONS}.
    136     *
    137     * @return <code>true</code> if cookies are allowed
    138     */
    139    boolean allowsCookieAssertions();
    140
    141    /**
    142     * Determines whether this Engine allows users to authenticate using cookies instead of passwords. This is determined by inspecting
    143     * the Engine property {@link #PROP_ALLOW_COOKIE_AUTH}.
    144     *
    145     *  @return <code>true</code> if cookies are allowed for authentication
    146     *  @since 2.5.62
    147     */
    148    boolean allowsCookieAuthentication();
    149
    150    /**
    151     * Instantiates and executes a single JAAS {@link LoginModule}, and returns a Set of Principals that results from a successful login.
    152     * The LoginModule is instantiated, then its {@link LoginModule#initialize(Subject, CallbackHandler, Map, Map)} method is called. The
    153     * parameters passed to <code>initialize</code> is a dummy Subject, an empty shared-state Map, and an options Map the caller supplies.
    154     *
    155     * @param clazz the LoginModule class to instantiate
    156     * @param handler the callback handler to supply to the LoginModule
    157     * @param options a Map of key/value strings for initializing the LoginModule
    158     * @return the set of Principals returned by the JAAS method {@link Subject#getPrincipals()}
    159     * @throws WikiSecurityException if the LoginModule could not be instantiated for any reason
    160     */
    161    Set< Principal > doJAASLogin( Class< ? extends LoginModule > clazz, CallbackHandler handler, Map< String, String > options) throws WikiSecurityException;
    162
    163    /**
    164     * Determines whether the supplied Principal is a "role principal".
    165     *
    166     * @param principal the principal to test
    167     * @return {@code true} if the Principal is of type {@link GroupPrincipal} or {@link Role}, {@code false} otherwise.
    168     */
    169    static boolean isRolePrincipal( final Principal principal ) {
    170        return principal instanceof Role || principal instanceof GroupPrincipal;
    171    }
    172
    173    /**
    174     * Determines whether the supplied Principal is a "user principal".
    175     *
    176     * @param principal the principal to test
    177     * @return {@code false} if the Principal is of type {@link GroupPrincipal} or {@link Role}, {@code true} otherwise.
    178     */
    179    static boolean isUserPrincipal( final Principal principal ) {
    180        return !isRolePrincipal( principal );
    181    }
    182
    183    /**
    184     * Returns the first Principal in a set that isn't a {@link Role} or {@link GroupPrincipal}.
    185     *
    186     * @param principals the principal set
    187     * @return the login principal
    188     */
    189    default Principal getLoginPrincipal( final Set< Principal > principals ) {
    190        return principals.stream().filter(AuthenticationManager::isUserPrincipal).findFirst().orElse(null);
    191    }
    192
    193    // events processing .......................................................
    194
    195    /**
    196     * Registers a WikiEventListener with this instance. This is a convenience method.
    197     *
    198     * @param listener the event listener
    199     */
    200    void addWikiEventListener( WikiEventListener listener );
    201
    202    /**
    203     * Un-registers a WikiEventListener with this instance. This is a convenience method.
    204     *
    205     * @param listener the event listener
    206     */
    207    void removeWikiEventListener( final WikiEventListener listener );
    208
    209    /**
    210     *  Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
    211     *
    212     * @see org.apache.wiki.event.WikiSecurityEvent
    213     * @param type       the event type to be fired
    214     * @param principal  the subject of the event, which may be <code>null</code>
    215     * @param target     the changed Object, which may be <code>null</code>
    216     */
    217    default void fireEvent( final int type, final Principal principal, final Object target ) {
    218        if ( WikiEventManager.isListening( this ) ) {
    219            WikiEventManager.fireEvent( this, new WikiSecurityEvent( this, type, principal, target ) );
    220        }
    221    }
    222
    223}