Interface Realm

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Add a property change listener to this component.
      java.security.Principal authenticate​(java.lang.String username)
      Try to authenticate with the specified username.
      java.security.Principal authenticate​(java.lang.String username, java.lang.String credentials)
      Try to authenticate using the specified username and credentials.
      java.security.Principal authenticate​(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2)
      Deprecated.
      Unused.
      default java.security.Principal authenticate​(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String digestA2, java.lang.String algorithm)
      Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
      java.security.Principal authenticate​(java.security.cert.X509Certificate[] certs)
      Try to authenticate using a chain of X509Certificates.
      java.security.Principal authenticate​(org.ietf.jgss.GSSContext gssContext, boolean storeCreds)
      Try to authenticate using a GSSContext.
      default java.security.Principal authenticate​(org.ietf.jgss.GSSName gssName, org.ietf.jgss.GSSCredential gssCredential)
      Try to authenticate using a GSSName.
      void backgroundProcess()
      Execute a periodic task, such as reloading, etc.
      SecurityConstraint[] findSecurityConstraints​(Request request, Context context)
      Find the SecurityConstraints configured to guard the request URI for this request.
      CredentialHandler getCredentialHandler()  
      java.lang.String[] getRoles​(java.security.Principal principal)
      Deprecated.
      This will be removed in Tomcat 10.
      boolean hasResourcePermission​(Request request, Response response, SecurityConstraint[] constraint, Context context)
      Perform access control based on the specified authorization constraint.
      boolean hasRole​(Wrapper wrapper, java.security.Principal principal, java.lang.String role)
      Check if the specified Principal has the specified security role, within the context of this Realm.
      boolean hasUserDataPermission​(Request request, Response response, SecurityConstraint[] constraint)
      Enforce any user data constraint required by the security constraint guarding this request URI.
      default boolean isAvailable()
      Return the availability of the realm for authentication.
      void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Remove a property change listener from this component.
      void setCredentialHandler​(CredentialHandler credentialHandler)
      Set the CredentialHandler to be used by this Realm.
    • Method Detail

      • getCredentialHandler

        CredentialHandler getCredentialHandler()
        Returns:
        the CredentialHandler configured for this Realm.
      • setCredentialHandler

        void setCredentialHandler​(CredentialHandler credentialHandler)
        Set the CredentialHandler to be used by this Realm.
        Parameters:
        credentialHandler - the CredentialHandler to use
      • addPropertyChangeListener

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

        java.security.Principal authenticate​(java.lang.String username)
        Try to authenticate with the specified username.
        Parameters:
        username - Username of the Principal to look up
        Returns:
        the associated principal, or null if none is associated.
      • authenticate

        java.security.Principal authenticate​(java.lang.String username,
                                             java.lang.String credentials)
        Try to authenticate using the specified username and credentials.
        Parameters:
        username - Username of the Principal to look up
        credentials - Password or other credentials to use in authenticating this username
        Returns:
        the associated principal, or null if there is none
      • authenticate

        @Deprecated
        java.security.Principal authenticate​(java.lang.String username,
                                             java.lang.String digest,
                                             java.lang.String nonce,
                                             java.lang.String nc,
                                             java.lang.String cnonce,
                                             java.lang.String qop,
                                             java.lang.String realm,
                                             java.lang.String digestA2)
        Deprecated.
        Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 2617 (which is a superset of RFC 2069).
        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
        nc - the nonce counter
        cnonce - the client chosen nonce
        qop - the "quality of protection" (nc and cnonce will only be used, if qop is not null).
        realm - Realm name
        digestA2 - Second digest calculated as digest(Method + ":" + uri)
        Returns:
        the associated principal, or null if there is none.
      • authenticate

        default java.security.Principal authenticate​(java.lang.String username,
                                                     java.lang.String digest,
                                                     java.lang.String nonce,
                                                     java.lang.String nc,
                                                     java.lang.String cnonce,
                                                     java.lang.String qop,
                                                     java.lang.String realm,
                                                     java.lang.String digestA2,
                                                     java.lang.String algorithm)
        Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.

        The default implementation calls authenticate(String, String, String, String, String, String, String, String) for backwards compatibility which effectively forces the use of MD5 regardless of the algorithm specified in the call to this method.

        Implementations are expected to override the default implementation and take account of the algorithm parameter.

        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
        nc - the nonce counter
        cnonce - the client chosen nonce
        qop - the "quality of protection" (nc and cnonce will only be used, if qop is not null).
        realm - Realm name
        digestA2 - Second digest calculated as digest(Method + ":" + uri)
        algorithm - The message digest algorithm to use
        Returns:
        the associated principal, or null if there is none.
      • authenticate

        java.security.Principal authenticate​(org.ietf.jgss.GSSContext gssContext,
                                             boolean storeCreds)
        Try to authenticate using a GSSContext.
        Parameters:
        gssContext - The gssContext processed by the Authenticator.
        storeCreds - Should the realm attempt to store the delegated credentials in the returned Principal?
        Returns:
        the associated principal, or null if there is none
      • authenticate

        default java.security.Principal authenticate​(org.ietf.jgss.GSSName gssName,
                                                     org.ietf.jgss.GSSCredential gssCredential)
        Try to authenticate using a GSSName. Note that this default method will be turned into an abstract one in Tomcat 10.
        Parameters:
        gssName - The GSSName of the principal to look up
        gssCredential - The GSSCredential of the principal, may be null
        Returns:
        the associated principal, or null if there is none
      • authenticate

        java.security.Principal authenticate​(java.security.cert.X509Certificate[] certs)
        Try to authenticate using a chain of X509Certificates.
        Parameters:
        certs - Array of client certificates, with the first one in the array being the certificate of the client itself.
        Returns:
        the associated principal, or null if there is none
      • backgroundProcess

        void backgroundProcess()
        Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.
      • findSecurityConstraints

        SecurityConstraint[] findSecurityConstraints​(Request request,
                                                     Context context)
        Find the SecurityConstraints configured to guard the request URI for this request.
        Parameters:
        request - Request we are processing
        context - Context the Request is mapped to
        Returns:
        the configured SecurityConstraint, or null if there is none
      • hasResourcePermission

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

        boolean hasRole​(Wrapper wrapper,
                        java.security.Principal principal,
                        java.lang.String role)
        Check if the specified Principal has the specified security role, within the context of this Realm.
        Parameters:
        wrapper - wrapper context for evaluating role
        principal - Principal for whom the role is to be checked
        role - Security role to be checked
        Returns:
        true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
      • hasUserDataPermission

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

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

        @Deprecated
        java.lang.String[] getRoles​(java.security.Principal principal)
        Deprecated.
        This will be removed in Tomcat 10.
        Return roles associated with given principal
        Parameters:
        principal - the Principal to get the roles for.
        Returns:
        principal roles
      • isAvailable

        default boolean isAvailable()
        Return the availability of the realm for authentication.
        Returns:
        true if the realm is able to perform authentication