Package org.apache.catalina.authenticator

Class AuthenticatorBase

  • All Implemented Interfaces:
    RegistrationListener, javax.management.MBeanRegistration, Authenticator, Contained, JmxEnabled, Lifecycle, Valve
    Direct Known Subclasses:
    BasicAuthenticator, DigestAuthenticator, FormAuthenticator, NonLoginAuthenticator, SpnegoAuthenticator, SSLAuthenticator
    public abstract class AuthenticatorBase
extends ValveBase
implements Authenticator, RegistrationListener
    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 omitted 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.

    Author:
    Craig R. McClanahan

    • Field Detail

      • sm

        protected static final StringManager sm
        The string manager for this package.

      • AUTH_HEADER_NAME

        protected static final java.lang.String AUTH_HEADER_NAME
        Authentication header
        See Also:
        Constant Field Values

      • REALM_NAME

        protected static final java.lang.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.

      • disableProxyCaching

        protected boolean disableProxyCaching
        Flag to determine if we disable proxy caching, or leave the issue up to the webapp developer.

      • securePagesWithPragma

        protected boolean securePagesWithPragma
        Flag to determine if we disable proxy caching with headers incompatible with IE.

      • secureRandomClass

        protected java.lang.String secureRandomClass
        The Java class name of the secure random number generator class to be used when generating SSO session identifiers. The random number generator class must be self-seeding and have a zero-argument constructor. If not specified, an instance of SecureRandom will be generated.

      • secureRandomAlgorithm

        protected java.lang.String secureRandomAlgorithm
        The name of the algorithm to use to create instances of SecureRandom which are used to generate SSO session IDs. If no algorithm is specified, SHA1PRNG is used. If SHA1PRNG is not available, the platform default will be used. To use the platform default (which may be SHA1PRNG), specify the empty string. If an invalid algorithm and/or provider is specified the SecureRandom instances will be created using the defaults. If that fails, the SecureRandom instances will be created using platform defaults.

      • secureRandomProvider

        protected java.lang.String secureRandomProvider
        The name of the provider to use to create instances of SecureRandom which are used to generate session SSO IDs. If no provider is specified the platform default is used. If an invalid algorithm and/or provider is specified the SecureRandom instances will be created using the defaults. If that fails, the SecureRandom instances will be created using platform defaults.

      • jaspicCallbackHandlerClass

        protected java.lang.String jaspicCallbackHandlerClass
        The name of the JASPIC callback handler class. If none is specified the default CallbackHandlerImpl will be used.

      • sso

        protected SingleSignOn sso
        The SingleSignOn implementation in our request processing chain, if there is one.

    • Constructor Detail

      • AuthenticatorBase

        public AuthenticatorBase()

    • Method Detail

      • getRealmName

        protected static java.lang.String getRealmName​(Context context)

      • getAllowCorsPreflight

        public java.lang.String getAllowCorsPreflight()

      • setAllowCorsPreflight

        public void setAllowCorsPreflight​(java.lang.String allowCorsPreflight)

      • getAlwaysUseSession

        public boolean getAlwaysUseSession()

      • setAlwaysUseSession

        public void setAlwaysUseSession​(boolean alwaysUseSession)

      • getCache

        public boolean getCache()
        Return the cache authenticated Principals flag.
        Returns:
        true if authenticated Principals will be cached, otherwise false

      • 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
        Returns:
        The Container with which this instance is associated or null if not associated with a Container

      • 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

      • getDisableProxyCaching

        public boolean getDisableProxyCaching()
        Return the flag that states if we add headers to disable caching by proxies.
        Returns:
        true if the headers will be added, otherwise false

      • 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.

      • getSecurePagesWithPragma

        public boolean getSecurePagesWithPragma()
        Return the flag that states, if proxy caching is disabled, what headers we add to disable the caching.
        Returns:
        true if a Pragma header should be used, otherwise false

      • 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.

      • getChangeSessionIdOnAuthentication

        public boolean getChangeSessionIdOnAuthentication()
        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.

      • getSecureRandomClass

        public java.lang.String getSecureRandomClass()
        Return the secure random number generator class name.
        Returns:
        The fully qualified name of the SecureRandom implementation to use

      • setSecureRandomClass

        public void setSecureRandomClass​(java.lang.String secureRandomClass)
        Set the secure random number generator class name.
        Parameters:
        secureRandomClass - The new secure random number generator class name

      • getSecureRandomAlgorithm

        public java.lang.String getSecureRandomAlgorithm()
        Return the secure random number generator algorithm name.
        Returns:
        The name of the SecureRandom algorithm used

      • setSecureRandomAlgorithm

        public void setSecureRandomAlgorithm​(java.lang.String secureRandomAlgorithm)
        Set the secure random number generator algorithm name.
        Parameters:
        secureRandomAlgorithm - The new secure random number generator algorithm name

      • getSecureRandomProvider

        public java.lang.String getSecureRandomProvider()
        Return the secure random number generator provider name.
        Returns:
        The name of the SecureRandom provider

      • setSecureRandomProvider

        public void setSecureRandomProvider​(java.lang.String secureRandomProvider)
        Set the secure random number generator provider name.
        Parameters:
        secureRandomProvider - The new secure random number generator provider name

      • getJaspicCallbackHandlerClass

        public java.lang.String getJaspicCallbackHandlerClass()
        Return the JASPIC callback handler class name
        Returns:
        The name of the JASPIC callback handler

      • setJaspicCallbackHandlerClass

        public void setJaspicCallbackHandlerClass​(java.lang.String jaspicCallbackHandlerClass)
        Set the JASPIC callback handler class name
        Parameters:
        jaspicCallbackHandlerClass - The new JASPIC callback handler class name

      • isSendAuthInfoResponseHeaders

        public boolean isSendAuthInfoResponseHeaders()
        Returns the flag whether authentication information will be sent to a reverse proxy on a forwarded request.
        Returns:
        true if response headers shall be sent, false otherwise

      • setSendAuthInfoResponseHeaders

        public void setSendAuthInfoResponseHeaders​(boolean sendAuthInfoResponseHeaders)
        Sets the flag whether authentication information will be send to a reverse proxy on a forwarded request.
        Parameters:
        sendAuthInfoResponseHeaders - true if response headers shall be sent, false otherwise

      • invoke

        public void invoke​(Request request,
                   Response response)
            throws java.io.IOException,
                   ServletException
        Enforce the security restrictions in the web application deployment descriptor of our associated Context.
        Specified by:
        invoke in interface Valve
        Parameters:
        request - Request to be processed
        response - Response to be processed
        Throws:
        java.io.IOException - if an input/output error occurs
        ServletException - if thrown by a processing element

      • allowCorsPreflightBypass

        protected boolean allowCorsPreflightBypass​(Request request)

      • authenticate

        public boolean authenticate​(Request request,
                            HttpServletResponse httpResponse)
                     throws java.io.IOException
        Description copied from interface: Authenticator
        Authenticate the user making this request, based on the login configuration of the Context with which this Authenticator is associated.
        Specified by:
        authenticate in interface Authenticator
        Parameters:
        request - Request we are processing
        httpResponse - Response we are populating
        Returns:
        true if any specified constraints have been satisfied, or false if one more constraints were not satisfied (in which case an authentication challenge will have been written to the response).
        Throws:
        java.io.IOException - if an input/output error occurs

      • doAuthenticate

        protected abstract boolean doAuthenticate​(Request request,
                                          HttpServletResponse response)
                                   throws java.io.IOException
        Provided for sub-classes to implement their specific authentication mechanism.
        Parameters:
        request - The request that triggered the authentication
        response - The response associated with the request
        Returns:
        true if the the user was authenticated, otherwise false, in which case an authentication challenge will have been written to the response
        Throws:
        java.io.IOException - If an I/O problem occurred during the authentication process

      • isContinuationRequired

        protected boolean isContinuationRequired​(Request request)
        Does this authenticator require that authenticate(Request, HttpServletResponse) is called to continue an authentication process that started in a previous request?
        Parameters:
        request - The request currently being processed
        Returns:
        true if authenticate() must be called, otherwise false

      • associate

        protected void associate​(java.lang.String ssoId,
                         Session session)
        Associate the specified single sign on identifier with the specified Session.
        Parameters:
        ssoId - Single sign on identifier
        session - Session to be associated

      • checkForCachedAuthentication

        protected boolean checkForCachedAuthentication​(Request request,
                                               HttpServletResponse response,
                                               boolean useSSO)
        Check to see if the user has already been authenticated earlier in the processing chain or if there is enough information available to authenticate the user without requiring further user interaction.
        Parameters:
        request - The current request
        response - The current response
        useSSO - Should information available from SSO be used to attempt to authenticate the current user?
        Returns:
        true if the user was authenticated via the cache, otherwise false

      • reauthenticateFromSSO

        protected boolean reauthenticateFromSSO​(java.lang.String ssoId,
                                        Request request)
        Attempts reauthentication to the Realm using the credentials included in argument entry.
        Parameters:
        ssoId - identifier of SingleSignOn session with which the caller is associated
        request - the request that needs to be authenticated
        Returns:
        true if the reauthentication from SSL occurred

      • register

        public void register​(Request request,
                     HttpServletResponse response,
                     java.security.Principal principal,
                     java.lang.String authType,
                     java.lang.String username,
                     java.lang.String 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)

      • register

        protected void register​(Request request,
                        HttpServletResponse response,
                        java.security.Principal principal,
                        java.lang.String authType,
                        java.lang.String username,
                        java.lang.String password,
                        boolean alwaysUseSession,
                        boolean cache)
        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)
        alwaysUseSession - Should a session always be used once a user is authenticated?
        cache - Should we cache authenticated Principals if the request is part of an HTTP session?

      • changeSessionID

        protected java.lang.String changeSessionID​(Request request,
                                           Session session)

      • getAuthMethod

        protected abstract java.lang.String getAuthMethod()

      • doLogin

        protected java.security.Principal doLogin​(Request request,
                                          java.lang.String username,
                                          java.lang.String password)
                                   throws ServletException
        Process the login request.
        Parameters:
        request - Associated request
        username - The user
        password - The password
        Returns:
        The authenticated Principal
        Throws:
        ServletException - No principal was authenticated with the specified credentials

      • isPreemptiveAuthPossible

        protected boolean isPreemptiveAuthPossible​(Request request)
        Can the authenticator perform preemptive authentication for the given request?
        Parameters:
        request - The request to check for credentials
        Returns:
        true if preemptive authentication is possible, otherwise false

      • notify

        public void notify​(java.lang.String layer,
                   java.lang.String appContext)
        Specified by:
        notify in interface RegistrationListener