AuthenticatorBase (Payara Project 5.2021.1 API)

java.lang.Object
- org.apache.catalina.valves.ValveBase
- - org.apache.catalina.authenticator.AuthenticatorBase

All Implemented Interfaces:

Authenticator, Contained, Lifecycle, Valve, GlassFishValve

Direct Known Subclasses:

AuthenticatorProxy, BasicAuthenticator, DigestAuthenticator, FormAuthenticator, NonLoginAuthenticator, SSLAuthenticator
```
public abstract class AuthenticatorBase
extends ValveBase
implements Authenticator
```
Basic implementation of the Valve interface that enforces the <security-constraint> elements in the web application deployment descriptor. This functionality is implemented as a Valve so that it can be ommitted in environments that do not require these features. Individual implementations of each supported authentication method can subclass this base class as required.
USAGE CONSTRAINT: When this class is utilized, the Context to which it is attached (or a parent Container in a hierarchy) must have an associated Realm that can be used for authenticating users and enumerating the roles to which they have been assigned.
USAGE CONSTRAINT: This Valve is only useful when processing HTTP requests. Requests of any other type will simply be passed through.

Version:

$Revision: 1.17.6.3 $ $Date: 2008/04/17 18:37:04 $

Author:

Craig R. McClanahan

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`alwaysUseSession` Should a session always be used once a user is authenticated? This may offer some performance benefits since the session can then be used to cache the authenticated Principal, hence removing the need to authenticate the user via the Realm on every request.
`protected static String`	`AUTH_HEADER_NAME` Authentication header
`protected boolean`	`cache` Should we cache authenticated Principals if the request is part of an HTTP session?
`protected boolean`	`changeSessionIdOnAuthentication` Should the session ID, if any, be changed upon a successful authentication to prevent a session fixation attack?
`protected Context`	`context` The Context to which this Valve is attached.
`protected boolean`	`disableProxyCaching` Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.
`protected String`	`entropy` A String initialization parameter used to increase the entropy of the initialization of our random number generator.
`protected static String`	`info` Descriptive information about this implementation.
`protected SecureRandom`	`random` A random number generator to use when generating session identifiers.
`protected String`	`randomClass` The Java class name of the random number generator class to be used when generating session identifiers.
`protected static String`	`REALM_NAME` Default authentication realm name.
`protected boolean`	`securePagesWithPragma` Flag to determine if we disable proxy caching with headers incompatible with IE
`protected static int`	`SESSION_ID_BYTES` The number of random bytes to include when generating a session identifier.
`protected SingleSignOn`	`sso` The SingleSignOn implementation in our request processing chain, if there is one.

Fields inherited from class org.apache.catalina.valves.ValveBase
container, controller, debug, domain, lifecycle, log, next, oname, rb, started

Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, INIT_EVENT, START_EVENT, STOP_EVENT

Fields inherited from interface org.glassfish.web.valve.GlassFishValve
END_PIPELINE, INVOKE_NEXT

Constructor Summary

Constructors
Constructor and Description

AuthenticatorBase()

Constructors
Constructor and Description
`AuthenticatorBase()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`associate(String ssoId, long ssoVersion, Session session)` Associate the specified single sign on identifier with the specified Session.
`abstract boolean`	`authenticate(HttpRequest request, HttpResponse response, LoginConfig config)` Authenticate the user making this request, based on the specified login configuration.
`protected Principal`	`doLogin(HttpRequest request, String username, char[] password)` Process the login request.
`protected String`	`generateSessionId()` Generate and return a new session identifier for the cookie that identifies an SSO principal.
`boolean`	`getAlwaysUseSession()`
`protected abstract String`	`getAuthMethod()`
`boolean`	`getCache()` Return the cache authenticated Principals flag.
`Container`	`getContainer()` Return the Container to which this Valve is attached.
`int`	`getDebug()` Return the debugging detail level for this component.
`boolean`	`getDisableProxyCaching()` Return the flag that states if we add headers to disable caching by proxies.
`String`	`getEntropy()` Return the entropy increaser value, or compute a semi-useful value if this String has not yet been set.
`String`	`getInfo()` Return descriptive information about this Valve implementation.
`protected SecureRandom`	`getRandom()` Return the random number generator instance we should use for generating session identifiers.
`String`	`getRandomClass()` Return the random number generator class name.
`String`	`getRealmName()` Returns the name of the associated realm.
`protected Session`	`getSession(HttpRequest request)` Return the internal Session that is associated with this HttpRequest, or `null` if there is no such Session.
`protected Session`	`getSession(HttpRequest request, boolean create)` Return the internal Session that is associated with this HttpRequest, possibly creating a new one if necessary, or `null` if there is no such session and we did not create one.
`SingleSignOn`	`getSingleSignOn()`
`int`	`invoke(Request request, Response response)` Enforce the security restrictions in the web application deployment descriptor of our associated Context.
`boolean`	`isChangeSessionIdOnAuthentication()` Return the flag that states if we should change the session ID of an existing session upon successful authentication.
`boolean`	`isSecurePagesWithPragma()` Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.
`protected void`	`log(String message)` Log a message on the Logger associated with our Container (if any).
`protected void`	`log(String message, Throwable t)` Log a message on the Logger associated with our Container (if any).
`void`	`login(String username, char[] password, HttpRequest request)`
`void`	`logout(HttpRequest request)`
`void`	`postInvoke(Request request, Response response)` A post-request processing implementation that does nothing.
`protected void`	`register(HttpRequest request, HttpResponse response, Principal principal, String authType, String username, char[] password)` Register an authenticated Principal and authentication type in our request, in the current session (if there is one), and with our SingleSignOn valve, if there is one.
`void`	`setAlwaysUseSession(boolean alwaysUseSession)`
`void`	`setCache(boolean cache)` Set the cache authenticated Principals flag.
`void`	`setChangeSessionIdOnAuthentication(boolean changeSessionIdOnAuthentication)` Set the value of the flag that states if we should change the session ID of an existing session upon successful authentication.
`void`	`setContainer(Container container)` Set the Container to which this Valve is attached.
`void`	`setDebug(int debug)` Set the debugging detail level for this component.
`void`	`setDisableProxyCaching(boolean nocache)` Set the value of the flag that states if we add headers to disable caching by proxies.
`void`	`setEntropy(String entropy)` Set the entropy increaser value.
`void`	`setRandomClass(String randomClass)` Set the random number generator class name.
`void`	`setRealmName(String name)` Set the name of the associated realm.
`void`	`setSecurePagesWithPragma(boolean securePagesWithPragma)` Set the value of the flag that states what headers we add to disable proxy caching.
`void`	`setSingleSignOn(SingleSignOn sso)`
`void`	`start()` Prepare for the beginning of active use of the public methods of this component.
`void`	`stop()` Gracefully terminate the active use of the public methods of this component.

Methods inherited from class org.apache.catalina.valves.ValveBase
addLifecycleListener, backgroundProcess, createObjectName, event, findLifecycleListeners, getController, getDomain, getNext, getObjectName, getParentName, invoke, isStarted, removeLifecycleListener, setController, setNext, setObjectName

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - info
```
protected static final String info
```
    Descriptive information about this implementation.
    
    See Also:
    
    Constant Field Values
  - SESSION_ID_BYTES
```
protected static final int SESSION_ID_BYTES
```
    The number of random bytes to include when generating a session identifier.
    
    See Also:
    
    Constant Field Values
  - AUTH_HEADER_NAME
```
protected static final String AUTH_HEADER_NAME
```
    Authentication header
    
    See Also:
    
    Constant Field Values
  - REALM_NAME
```
protected static final String REALM_NAME
```
    Default authentication realm name.
    
    See Also:
    
    Constant Field Values
  - alwaysUseSession
```
protected boolean alwaysUseSession
```
    Should a session always be used once a user is authenticated? This may offer some performance benefits since the session can then be used to cache the authenticated Principal, hence removing the need to authenticate the user via the Realm on every request. This may be of help for combinations such as BASIC authentication used with the JNDIRealm or DataSourceRealms. However there will also be the performance cost of creating and GC'ing the session. By default, a session will not be created.
  - cache
```
protected boolean cache
```
    Should we cache authenticated Principals if the request is part of an HTTP session?
  - changeSessionIdOnAuthentication
```
protected boolean changeSessionIdOnAuthentication
```
    Should the session ID, if any, be changed upon a successful authentication to prevent a session fixation attack?
  - context
```
protected Context context
```
    The Context to which this Valve is attached.
  - entropy
```
protected String entropy
```
    A String initialization parameter used to increase the entropy of the initialization of our random number generator.
  - disableProxyCaching
```
protected boolean disableProxyCaching
```
    Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.
  - random
```
protected SecureRandom random
```
    A random number generator to use when generating session identifiers.
  - randomClass
```
protected String randomClass
```
    The Java class name of the random number generator class to be used when generating session identifiers.
  - sso
```
protected SingleSignOn sso
```
    The SingleSignOn implementation in our request processing chain, if there is one.
  - securePagesWithPragma
```
protected boolean securePagesWithPragma
```
    Flag to determine if we disable proxy caching with headers incompatible with IE
- Constructor Detail
  - AuthenticatorBase
```
public AuthenticatorBase()
```
- Method Detail
  - getAlwaysUseSession
```
public boolean getAlwaysUseSession()
```
  - setAlwaysUseSession
```
public void setAlwaysUseSession(boolean alwaysUseSession)
```
  - getCache
```
public boolean getCache()
```
    Return the cache authenticated Principals flag.
  - setCache
```
public void setCache(boolean cache)
```
    Set the cache authenticated Principals flag.
    
    Parameters:
    
    cache - The new cache flag
  - getContainer
```
public Container getContainer()
```
    Return the Container to which this Valve is attached.
    
    Specified by:
    
    getContainer in interface Contained
    
    Overrides:
    
    getContainer in class ValveBase
  - setContainer
```
public void setContainer(Container container)
```
    Set the Container to which this Valve is attached.
    
    Specified by:
    
    setContainer in interface Contained
    
    Overrides:
    
    setContainer in class ValveBase
    
    Parameters:
    
    container - The container to which we are attached
  - getDebug
```
public int getDebug()
```
    Return the debugging detail level for this component.
    
    Overrides:
    
    getDebug in class ValveBase
  - setDebug
```
public void setDebug(int debug)
```
    Set the debugging detail level for this component.
    
    Overrides:
    
    setDebug in class ValveBase
    
    Parameters:
    
    debug - The new debugging detail level
  - getEntropy
```
public String getEntropy()
```
    Return the entropy increaser value, or compute a semi-useful value if this String has not yet been set.
  - setEntropy
```
public void setEntropy(String entropy)
```
    Set the entropy increaser value.
    
    Parameters:
    
    entropy - The new entropy increaser value
  - getInfo
```
public String getInfo()
```
    Return descriptive information about this Valve implementation.
    
    Specified by:
    
    getInfo in interface Valve
    
    Specified by:
    
    getInfo in interface GlassFishValve
    
    Overrides:
    
    getInfo in class ValveBase
  - getRandomClass
```
public String getRandomClass()
```
    Return the random number generator class name.
  - setRandomClass
```
public void setRandomClass(String randomClass)
```
    Set the random number generator class name.
    
    Parameters:
    
    randomClass - The new random number generator class name
  - getDisableProxyCaching
```
public boolean getDisableProxyCaching()
```
    Return the flag that states if we add headers to disable caching by proxies.
  - setDisableProxyCaching
```
public void setDisableProxyCaching(boolean nocache)
```
    Set the value of the flag that states if we add headers to disable caching by proxies.
    
    Parameters:
    
    nocache - true if we add headers to disable proxy caching, false if we leave the headers alone.
  - isSecurePagesWithPragma
```
public boolean isSecurePagesWithPragma()
```
    Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.
  - setSecurePagesWithPragma
```
public void setSecurePagesWithPragma(boolean securePagesWithPragma)
```
    Set the value of the flag that states what headers we add to disable proxy caching.
    
    Parameters:
    
    securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozilla.
  - isChangeSessionIdOnAuthentication
```
public boolean isChangeSessionIdOnAuthentication()
```
    Return the flag that states if we should change the session ID of an existing session upon successful authentication.
    
    Returns:
    
    true to change session ID upon successful authentication, false to do not perform the change.
  - setChangeSessionIdOnAuthentication
```
public void setChangeSessionIdOnAuthentication(boolean changeSessionIdOnAuthentication)
```
    Set the value of the flag that states if we should change the session ID of an existing session upon successful authentication.
    
    Parameters:
    
    changeSessionIdOnAuthentication - true to change session ID upon successful authentication, false to do not perform the change.
  - getSingleSignOn
```
public SingleSignOn getSingleSignOn()
```
  - setSingleSignOn
```
public void setSingleSignOn(SingleSignOn sso)
```
  - invoke
```
public int invoke(Request request,
                  Response response)
           throws IOException,
                  javax.servlet.ServletException
```
    Enforce the security restrictions in the web application deployment descriptor of our associated Context.
    
    Specified by:
    
    invoke in interface GlassFishValve
    
    Specified by:
    
    invoke in class ValveBase
    
    Parameters:
    
    request - Request to be processed
    
    response - Response to be processed
    
    Returns:
    
    INVOKE_NEXT or END_PIPELINE
    
    Throws:
    
    IOException - if an input/output error occurs
    
    javax.servlet.ServletException - if thrown by a processing element
  - postInvoke
```
public void postInvoke(Request request,
                       Response response)
                throws IOException,
                       javax.servlet.ServletException
```
    A post-request processing implementation that does nothing. Very few Valves override this behaviour as most Valve logic is used for request processing.
    
    Specified by:
    
    postInvoke in interface GlassFishValve
    
    Overrides:
    
    postInvoke in class ValveBase
    
    Parameters:
    
    request - The servlet request to be processed
    
    response - The servlet response to be created
    
    Throws:
    
    IOException - if an input/output error occurs
    
    javax.servlet.ServletException - if a servlet error occurs
  - associate
```
protected void associate(String ssoId,
                         long ssoVersion,
                         Session session)
```
    Associate the specified single sign on identifier with the specified Session.
    
    Parameters:
    
    ssoId - Single sign on identifier
    
    ssoVersion - Single sign on version
    
    session - Session to be associated
  - authenticate
```
public abstract boolean authenticate(HttpRequest request,
                                     HttpResponse response,
                                     LoginConfig config)
                              throws IOException
```
    Authenticate the user making this request, based on the specified login configuration. Return true if any specified constraint has been satisfied, or false if we have created a response challenge already.
    
    Parameters:
    
    request - Request we are processing
    
    response - Response we are creating
    
    config - Login configuration describing how authentication should be performed
    
    Throws:
    
    IOException - if an input/output error occurs
  - generateSessionId
```
protected String generateSessionId()
```
    Generate and return a new session identifier for the cookie that identifies an SSO principal.
  - getRandom
```
protected SecureRandom getRandom()
```
    Return the random number generator instance we should use for generating session identifiers. If there is no such generator currently defined, construct and seed a new one.
  - getSession
```
protected Session getSession(HttpRequest request)
```
    Return the internal Session that is associated with this HttpRequest, or null if there is no such Session.
    
    Parameters:
    
    request - The HttpRequest we are processing
  - getSession
```
protected Session getSession(HttpRequest request,
                             boolean create)
```
    Return the internal Session that is associated with this HttpRequest, possibly creating a new one if necessary, or null if there is no such session and we did not create one.
    
    Parameters:
    
    request - The HttpRequest we are processing
    
    create - Should we create a session if needed?
  - log
```
protected void log(String message)
```
    Log a message on the Logger associated with our Container (if any).
    
    Parameters:
    
    message - Message to be logged
  - log
```
protected void log(String message,
                   Throwable t)
```
    Log a message on the Logger associated with our Container (if any).
    
    Parameters:
    
    message - Message to be logged
    
    t - Associated exception
  - register
```
protected void register(HttpRequest request,
                        HttpResponse response,
                        Principal principal,
                        String authType,
                        String username,
                        char[] password)
```
    Register an authenticated Principal and authentication type in our request, in the current session (if there is one), and with our SingleSignOn valve, if there is one. Set the appropriate cookie to be returned.
    
    Parameters:
    
    request - The servlet request we are processing
    
    response - The servlet response we are generating
    
    principal - The authenticated Principal to be registered
    
    authType - The authentication type to be registered
    
    username - Username used to authenticate (if any)
    
    password - Password used to authenticate (if any)
  - login
```
public void login(String username,
                  char[] password,
                  HttpRequest request)
           throws javax.servlet.ServletException
```
    Specified by:
    
    login in interface Authenticator
    
    Throws:
    
    javax.servlet.ServletException
  - getAuthMethod
```
protected abstract String getAuthMethod()
```
  - doLogin
```
protected Principal doLogin(HttpRequest request,
                            String username,
                            char[] password)
                     throws javax.servlet.ServletException
```
    Process the login request.
    
    Parameters:
    
    request - Associated request
    
    username - The user
    
    password - The password
    
    Returns:
    
    The authenticated Principal
    
    Throws:
    
    javax.servlet.ServletException
  - logout
```
public void logout(HttpRequest request)
            throws javax.servlet.ServletException
```
    Specified by:
    
    logout in interface Authenticator
    
    Throws:
    
    javax.servlet.ServletException
  - start
```
public void start()
           throws LifecycleException
```
    Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.
    
    Specified by:
    
    start in interface Lifecycle
    
    Overrides:
    
    start in class ValveBase
    
    Throws:
    
    LifecycleException - if this component detects a fatal error that prevents this component from being used
  - stop
```
public void stop()
          throws LifecycleException
```
    Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.
    
    Specified by:
    
    stop in interface Lifecycle
    
    Overrides:
    
    stop in class ValveBase
    
    Throws:
    
    LifecycleException - if this component detects a fatal error that needs to be reported
  - setRealmName
```
public void setRealmName(String name)
```
    Set the name of the associated realm. This method does nothing by default.
    
    Parameters:
    
    name - the name of the realm.
  - getRealmName
```
public String getRealmName()
```
    Returns the name of the associated realm. Always returns null unless subclass overrides behavior.
    
    Returns:
    
    realm name or null if not set.

Class AuthenticatorBase

Field Summary

Fields inherited from class org.apache.catalina.valves.ValveBase

Fields inherited from interface org.apache.catalina.Lifecycle

Fields inherited from interface org.glassfish.web.valve.GlassFishValve

Constructor Summary

Method Summary

Methods inherited from class org.apache.catalina.valves.ValveBase

Methods inherited from class java.lang.Object

Field Detail

info

SESSION_ID_BYTES

AUTH_HEADER_NAME

REALM_NAME

alwaysUseSession

cache

changeSessionIdOnAuthentication

context

entropy

disableProxyCaching

random

randomClass

sso

securePagesWithPragma

Constructor Detail

AuthenticatorBase

Method Detail

getAlwaysUseSession

setAlwaysUseSession

getCache

setCache

getContainer

setContainer

getDebug

setDebug

getEntropy

setEntropy

getInfo

getRandomClass

setRandomClass

getDisableProxyCaching

setDisableProxyCaching

isSecurePagesWithPragma

setSecurePagesWithPragma

isChangeSessionIdOnAuthentication

setChangeSessionIdOnAuthentication

getSingleSignOn

setSingleSignOn

invoke

postInvoke

associate

authenticate

generateSessionId

getRandom

getSession

getSession

log

log

register

login

getAuthMethod

doLogin

logout

start

stop

setRealmName

getRealmName