com.caucho.server.security.ServletAuthenticator Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1998-2018 Caucho Technology -- all rights reserved
 *
 * This file is part of Resin(R) Open Source
 *
 * Each copy or derived work must preserve the copyright notice and this
 * notice unmodified.
 *
 * Resin Open Source is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * Resin Open Source is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
 * of NON-INFRINGEMENT.  See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Resin Open Source; if not, write to the
 *
 *   Free Software Foundation, Inc.
 *   59 Temple Place, Suite 330
 *   Boston, MA 02111-1307  USA
 *
 * @author Scott Ferguson
 */

package com.caucho.server.security;

import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.security.Principal;

/**
 * Used in conjunction with AbstractLogin to authenticate users in
 * a servlet request.  The ServletAuthenticator is typically responsible for
 * the actual authentication and AbstractLogin is responsible for extracting
 * credentials (user and password) from the request and returning any
 * error pages.  Since Login classes typically delegate to the Authenticator,
 * the same authenticator can be used for "basic", "form" or a custom login.
 *
 * In general, applications should extend AbstractAuthenticator instead
 * to protect from API changes in the Authenticator.
 *
 * 
The authenticator is configured using init-param in the resin.conf.
 * For example, if test.MyAuthenticator defines a setFoo method,
 * it can be configured with <init-param foo='bar'/>.
 *
 * 
 * <authenticator url='scheme:param1=value1;param2=value2'>
 *   <init>
 *     <param3>value4</param3>
 *   </init>
 * </authenticator>
 * 
 *
 * Authenticator instances can be specific to a web-app, host, or
 * server-wide.  If the authenticator is configured for the host, it
 * is shared for all web-apps in that host, enabling single-signon.
 *
 * 
 * <host id='foo'>
 *   <authenticator id='myauth'>...</authenticator>
 *
 *   <web-app id='/a'>
 *     ...
 *   </web-app>
 *
 *   <web-app id='/a'>
 *     ...
 *   </web-app>
 * </host>
 * 
 */
public interface ServletAuthenticator {
  /**
   * Initialize the authenticator.  init() is called after all
   * the bean parameter have been set.
   */
  public void init()
    throws ServletException;
  
  /**
   * Logs a user in with a user name and a password.  The login method
   * is generally called during servlet security checks.  The
   * ServletRequest.getUserPrincipal call will generally call
   * getUserPrincipal.
   *
   * The implementation may only use the response to set cookies
   * and headers.  It may not write output or set the response status.
   * If the application needs to send a custom error reponse,
   * it must implement a custom AbstractLogin instead.
   *
   * @param request servlet request
   * @param response servlet response, in case any cookie need sending.
   * @param application servlet application
   * @param user the user name.
   * @param password the users input password.
   *
   * @return the logged in principal on success, null on failure.
   */
  public Principal login(HttpServletRequest request,
                         HttpServletResponse response,
                         ServletContext application,
                         String user, String password)
    throws ServletException;
  
  /**
   * Gets the authenticated user for the current request.  If the user
   * has not logged in, just returns null.
   *
   * 
getUserPrincipal is called in response to an application's call to
   * HttpServletRequest.getUserPrincipal.
   *
   * 
The implementation may only use the response to set cookies
   * and headers.  It may not write output.
   *
   * @param request the request trying to authenticate.
   * @param response the response for setting headers and cookies.
   * @param application the servlet context
   *
   * @return the authenticated user or null if none has logged in
   */
  public Principal getUserPrincipal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    ServletContext application)
    throws ServletException;
  
  /**
   * Validates the user when using HTTP Digest authentication.
   * DigestLogin will call this method.  Most other AbstractLogin
   * implementations, like BasicLogin and FormLogin, will use
   * getUserPrincipal instead.
   *
   * 
The HTTP Digest authentication uses the following algorithm
   * to calculate the digest.  The digest is then compared to
   * the client digest.
   *
   * 
   * A1 = MD5(username + ':' + realm + ':' + password)
   * A2 = MD5(method + ':' + uri)
   * digest = MD5(A1 + ':' + nonce + A2)
   * 
   *
   * @param request the request trying to authenticate.
   * @param response the response for setting headers and cookies.
   * @param app the servlet context
   * @param user the username
   * @param realm the authentication realm
   * @param nonce the nonce passed to the client during the challenge
   * @param uri te protected uri
   * @param qop
   * @param nc
   * @param cnonce the client nonce
   * @param clientDigest the client's calculation of the digest
   *
   * @return the logged in principal if successful
   */
  public Principal loginDigest(HttpServletRequest request,
                               HttpServletResponse response,
                               ServletContext app,
                               String user, String realm,
                               String nonce, String uri,
                               String qop, String nc, String cnonce,
                               byte []clientDigset)
    throws ServletException;
  
  /**
   * Returns true if the user plays the named role.
   *
   * This method is called in response to the
   * HttpServletResponse.isUserInRole call and for security-constraints
   * that check the use role.
   *
   * @param request the request testing the role.
   * @param application the owning application
   * @param user the user's Principal.
   * @param role role name.
   */
  public boolean isUserInRole(HttpServletRequest request,
                              HttpServletResponse response,
                              ServletContext application,
                              Principal user, String role)
    throws ServletException;
  
  /**
   * Logs the user out from the given request.
   *
   * Called via the session.logout() method.
   *
   * @param session for timeout, the session timing out. null if force logout
   */
  public void logout(ServletContext application,
                     HttpSession session,
                     String sessionId,
                     Principal user)
    throws ServletException;
}