Package org.apache.catalina

Interface Realm

  • All Known Implementing Classes:
    JAASRealm, RealmAdapter, RealmBase
    @Contract
@PerLookup
public interface Realm
    A Realm is a read-only facade for an underlying security realm used to authenticate individual users, and identify the security roles associated with those users. Realms can be attached at any Container level, but will typically only be attached to a Context, or higher level, Container.
    Version:
    $Revision: 1.6 $ $Date: 2007/04/18 17:27:22 $
    Author:
    Craig R. McClanahan

    • Field Detail

      • AUTHENTICATE_NEEDED

        static final int AUTHENTICATE_NEEDED
        Flag indicating authentication is needed for current request. Used by preAuthenticateCheck method.
        See Also:
        Constant Field Values

      • AUTHENTICATE_NOT_NEEDED

        static final int AUTHENTICATE_NOT_NEEDED
        Flag indicating authentication is not needed for current request. Used by preAuthenticateCheck method.
        See Also:
        Constant Field Values

      • AUTHENTICATED_NOT_AUTHORIZED

        static final int AUTHENTICATED_NOT_AUTHORIZED
        Flag indicating the user has been authenticated but been denied access to the requested resource.
        See Also:
        Constant Field Values

    • Method Detail

      • getContainer

        Container getContainer()
        Return the Container with which this Realm has been associated.

      • setContainer

        void setContainer​(Container container)
        Set the Container with which this Realm has been associated.
        Parameters:
        container - The associated Container

      • getInfo

        String getInfo()
        Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.

      • addPropertyChangeListener

        void addPropertyChangeListener​(PropertyChangeListener listener)
        Add a property change listener to this component.
        Parameters:
        listener - The listener to add

      • authenticate

        Principal authenticate​(String username,
                       char[] credentials)
        Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
        Parameters:
        username - Username of the Principal to look up
        credentials - Password or other credentials to use in authenticating this username

      • authenticate

        Principal authenticate​(String username,
                       char[] digest,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String realm,
                       char[] md5a2)
        Return the Principal associated with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2069; otherwise return null.
        Parameters:
        username - Username of the Principal to look up
        digest - Digest which has been submitted by the client
        nonce - Unique (or supposedly unique) token which has been used for this request
        realm - Realm name
        md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)

      • authenticate

        Principal authenticate​(X509Certificate[] certs)
        Return the Principal associated with the specified chain of X509 client certificates. If there is none, return null.
        Parameters:
        certs - Array of client certificates, with the first one in the array being the certificate of the client itself.

      • authenticate

        Principal authenticate​(jakarta.servlet.http.HttpServletRequest hreq)
        Does digest authentication and returns the Principal associated with the username in the HTTP header.
        Parameters:
        hreq - HTTP servlet request.

      • findSecurityConstraints

        SecurityConstraint[] findSecurityConstraints​(HttpRequest request,
                                             Context context)
        Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.
        Parameters:
        request - Request we are processing

      • findSecurityConstraints

        SecurityConstraint[] findSecurityConstraints​(String uri,
                                             String method,
                                             Context context)
        Gets the security constraints configured by the given context for the given request URI and method.
        Parameters:
        uri - the request URI
        method - the request method
        context - the context
        Returns:
        the security constraints configured by the given context for the given request URI and method, or null

      • hasResourcePermission

        boolean hasResourcePermission​(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint,
                              Context context)
                       throws IOException
        Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraint - Security constraint we are enforcing
        context - Context to which client of this class is attached.
        Throws:
        IOException - if an input/output error occurs

      • hasRole

        boolean hasRole​(Principal principal,
                String role)
        Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
        Parameters:
        principal - Principal for whom the role is to be checked
        role - Security role to be checked

      • hasRole

        boolean hasRole​(HttpRequest request,
                HttpResponse response,
                Principal principal,
                String role)
        Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        principal - Principal for whom the role is to be checked
        role - Security role to be checked

      • preAuthenticateCheck

        int preAuthenticateCheck​(HttpRequest request,
                         HttpResponse response,
                         SecurityConstraint[] constraints,
                         boolean disableProxyCaching,
                         boolean securePagesWithPragma,
                         boolean ssoEnabled)
                  throws IOException
        Checks whether or not authentication is needed. Returns an int, one of AUTHENTICATE_NOT_NEEDED, AUTHENTICATE_NEEDED, or AUTHENTICATED_NOT_AUTHORIZED.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraints - Security constraint we are enforcing
        disableProxyCaching - whether or not to disable proxy caching for protected resources.
        securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozill
        ssoEnabled - true if sso is enabled
        Throws:
        IOException - if an input/output error occurs

      • invokeAuthenticateDelegate

        boolean invokeAuthenticateDelegate​(HttpRequest request,
                                   HttpResponse response,
                                   Context context,
                                   Authenticator authenticator,
                                   boolean calledFromAuthenticate)
                            throws IOException
        Authenticates the user making this request, based on the specified login configuration. Return true if any specified requirements have been satisfied, or false if we have created a response challenge already.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        context - The Context to which client of this class is attached.
        authenticator - the current authenticator.
        calledFromAuthenticate - true if the call originates from HttpServletRequest.authenticate
        Throws:
        IOException - if an input/output error occurs

      • invokePostAuthenticateDelegate

        boolean invokePostAuthenticateDelegate​(HttpRequest request,
                                       HttpResponse response,
                                       Context context)
                                throws IOException
        Post authentication for given request and response.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        context - The Context to which client of this class is attached.
        Throws:
        IOException - if an input/output error occurs

      • hasUserDataPermission

        boolean hasUserDataPermission​(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint)
                       throws IOException
        Enforce any user data constraint required by the security constraint guarding this request URI. Return true if this constraint was not violated and processing should continue, or false if we have created a response already.
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraint - Security constraint being checked
        Throws:
        IOException - if an input/output error occurs

      • hasUserDataPermission

        boolean hasUserDataPermission​(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraints,
                              String uri,
                              String method)
                       throws IOException
        Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied. If uri and method are null, then the URI and method of the given request are checked. If a user-data-constraint exists that is not satisfied, then the given request will be redirected to HTTPS.
        Parameters:
        request - the request that may be redirected
        response - the response that may be redirected
        constraints - the security constraints to check against
        uri - the request URI (minus the context path) to check
        method - the request method to check
        Returns:
        true if the request URI and method are not the target of any unsatisfied user-data-constraint with a transport-guarantee of CONFIDENTIAL, and false if they are (in which case the given request will have been redirected to HTTPS)
        Throws:
        IOException

      • removePropertyChangeListener

        void removePropertyChangeListener​(PropertyChangeListener listener)
        Remove a property change listener from this component.
        Parameters:
        listener - The listener to remove

      • getAlternatePrincipal

        Principal getAlternatePrincipal​(HttpRequest req)
        Return an alternate principal from the request if available.
        Parameters:
        req - The request object.
        Returns:
        Alternate principal or null.

      • getAlternateAuthType

        String getAlternateAuthType​(HttpRequest req)
        Return an alternate auth type from the request if available.
        Parameters:
        req - The request object.
        Returns:
        Alternate auth type or null.

      • setRealmName

        void setRealmName​(String name,
                  String authMethod)
        Set the name of the associated realm.
        Parameters:
        name - the name of the realm.

      • getRealmName

        String getRealmName()
        Returns the name of the associated realm.
        Returns:
        realm name or null if not set.

      • isSecurityExtensionEnabled

        boolean isSecurityExtensionEnabled​(jakarta.servlet.ServletContext servletContext)
        Returns whether the specified ServletContext indicates that security extension is enabled.
        Parameters:
        servletContext - the ServletContext
        Returns:
        true if security extension is enabled; false otherwise

      • logout

        void logout​(HttpRequest hreq)
        Logs out.
        Parameters:
        hreq - the HttpRequest