/*********************************************************** * $Id$ * * HTTP Utility classes of the clazzes.org project * http://www.clazzes.org * * Created: 02.04.2011 * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * ***********************************************************/ package org.clazzes.util.http.sec; import java.security.Principal; import javax.servlet.http.HttpServletRequest; /** * An interface, which provides a login facility to an application. */ public interface HttpLoginService { /** * The name of the OSGi property, which defines the login method. */ public static final String LOGIN_MECHANISM_KEY = "login.mechanism"; /** *
Return an URL to web page, which authenticates the user,
* usually using a form POST. The web page is intended to be
* embedded by a consuming application inside an HTML
* iframe
element.
By convention, the application must have an invisible form named
* loginResultForm
in which the login page at least sets the
* hidden fields status
and principal
containing
* the login status according to the HTTP standard and the user name.
The following status values are supported:
*Status | Description |
---|---|
401 | Unauthorized - The default status, if the HTTP session is not authenticated. |
403 | Forbidden - The status, which will be returned by an unsuccessful authentication. |
406 | Not Acceptable - The status, which will be returned after to many unsuccessful authentications. |
200 | OK - The status, which will be returned by a successful authentication,
* the principal field will be set. |
All other status values should be interpreted like 401 - Unauthorized
and the user
* should try to login again.
* A login service is exported as OSGi service using a login.mechnism
service
* property, which allows different application to choose among several login service implementations.
*
* <bp:service id="loginServiceService" interface="org.clazzes.util.http.sec.HttpLoginService" * ref="loginService"> * <bp:service-properties> * <bp:entry key="login.mechanism" value="org.clazzes.gwt.login.jaas"/> * </bp:service-properties> * </bp:service> ** * * @return An URL to a login application, which may be started inside * an
iframe
of a consuming application.
*/
public String getLoginUrl();
/**
* Get the principal associated with the HTTP session of the given request.
* @param request The HTTP request to query for an associated user.
* @return A user principal or null
, if no user
* has been validated for the session of this request.
*/
public Principal checkLogin(HttpServletRequest request);
/**
* Check, whether the authenticated user of the given HttpServletRequest
* has permissions on the given context. The context is usually a relative
* URL like /app/object?id=862346&action=read
.
*
* @param request The HTTP request to check.
* @param context The context, usually encoded as URL.
* @return Whether the user associated with the request is given
* access to the specified context.
*/
public boolean checkPermission(HttpServletRequest request, String context);
/**
* Remove all attributes generated during a login process from
* the HTTP session of the given request.
*
* @param request A HTTP request on which to perform a logout.
*/
public void logout(HttpServletRequest request);
}