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        for( final Principal principal : principals ) {
191            if ( isUserPrincipal( principal ) ) {
192                return principal;
193            }
194        }
195        return null;
196    }
197
198    // events processing .......................................................
199
200    /**
201     * Registers a WikiEventListener with this instance. This is a convenience method.
202     *
203     * @param listener the event listener
204     */
205    void addWikiEventListener( WikiEventListener listener );
206
207    /**
208     * Un-registers a WikiEventListener with this instance. This is a convenience method.
209     *
210     * @param listener the event listener
211     */
212    void removeWikiEventListener( final WikiEventListener listener );
213
214    /**
215     *  Fires a WikiSecurityEvent of the provided type, Principal and target Object to all registered listeners.
216     *
217     * @see org.apache.wiki.event.WikiSecurityEvent
218     * @param type       the event type to be fired
219     * @param principal  the subject of the event, which may be <code>null</code>
220     * @param target     the changed Object, which may be <code>null</code>
221     */
222    default void fireEvent( final int type, final Principal principal, final Object target ) {
223        if ( WikiEventManager.isListening( this ) ) {
224            WikiEventManager.fireEvent( this, new WikiSecurityEvent( this, type, principal, target ) );
225        }
226    }
227
228}