Package org.apache.catalina.realm

Class RealmBase

    • Field Detail

      • USER_ATTRIBUTES_DELIMITER

        protected static final java.lang.String USER_ATTRIBUTES_DELIMITER
        The character used for delimiting user attribute names.

        Applies to some of the Realm implementations only.

        See Also:
        Constant Field Values

      • USER_ATTRIBUTES_WILDCARD

        protected static final java.lang.String USER_ATTRIBUTES_WILDCARD
        The character used as wildcard in user attribute lists. Using it means query all available user attributes.

        Applies to some of the Realm implementations only.

        See Also:
        Constant Field Values

      • container

        protected Container container
        The Container with which this Realm is associated.

      • containerLog

        protected Log containerLog
        Container log

      • sm

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

      • support

        protected final java.beans.PropertyChangeSupport support
        The property change support for this component.

      • validate

        protected boolean validate
        Should we validate client certificate chains when they are presented?

      • x509UsernameRetrieverClassName

        protected java.lang.String x509UsernameRetrieverClassName
        The name of the class to use for retrieving user names from X509 certificates.

      • x509UsernameRetriever

        protected X509UsernameRetriever x509UsernameRetriever
        The object that will extract user names from X509 client certificates.

      • stripRealmForGss

        protected boolean stripRealmForGss
        When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?

      • userAttributes

        protected java.lang.String userAttributes
        The comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.

      • userAttributesList

        protected java.util.List<java.lang.String> userAttributesList
        The list of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. Support for this feature is optional.

      • realmPath

        protected java.lang.String realmPath

    • Constructor Detail

      • RealmBase

        public RealmBase()

    • Method Detail

      • getTransportGuaranteeRedirectStatus

        public int getTransportGuaranteeRedirectStatus()
        Returns:
        The HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.

      • setTransportGuaranteeRedirectStatus

        public void setTransportGuaranteeRedirectStatus​(int transportGuaranteeRedirectStatus)
        Set the HTTP status code used when the container needs to issue an HTTP redirect to meet the requirements of a configured transport guarantee.
        Parameters:
        transportGuaranteeRedirectStatus - The status to use. This value is not validated

      • getContainer

        public Container getContainer()
        Description copied from interface: Contained
        Get the Container with which this instance is associated.
        Specified by:
        getContainer in interface Contained
        Returns:
        The Container with which this instance is associated or null if not associated with a Container

      • setContainer

        public void setContainer​(Container container)
        Description copied from interface: Contained
        Set the Container with which this instance is associated.
        Specified by:
        setContainer in interface Contained
        Parameters:
        container - The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container

      • getAllRolesMode

        public java.lang.String getAllRolesMode()
        Return the all roles mode.
        Returns:
        A string representation of the current all roles mode

      • setAllRolesMode

        public void setAllRolesMode​(java.lang.String allRolesMode)
        Set the all roles mode.
        Parameters:
        allRolesMode - A string representation of the new all roles mode

      • getValidate

        public boolean getValidate()
        Return the "validate certificate chains" flag.
        Returns:
        The value of the validate certificate chains flag

      • setValidate

        public void setValidate​(boolean validate)
        Set the "validate certificate chains" flag.
        Parameters:
        validate - The new validate certificate chains flag

      • getX509UsernameRetrieverClassName

        public java.lang.String getX509UsernameRetrieverClassName()
        Gets the name of the class that will be used to extract user names from X509 client certificates.
        Returns:
        The name of the class that will be used to extract user names from X509 client certificates.

      • setX509UsernameRetrieverClassName

        public void setX509UsernameRetrieverClassName​(java.lang.String className)
        Sets the name of the class that will be used to extract user names from X509 client certificates. The class must implement X509UsernameRetriever.
        Parameters:
        className - The name of the class that will be used to extract user names from X509 client certificates.
        See Also:
        X509UsernameRetriever

      • isStripRealmForGss

        public boolean isStripRealmForGss()

      • setStripRealmForGss

        public void setStripRealmForGss​(boolean stripRealmForGss)

      • getUserAttributes

        public java.lang.String getUserAttributes()
        Returns:
        the comma separated names of user attributes to additionally query from realm

      • setUserAttributes

        public void setUserAttributes​(java.lang.String userAttributes)
        Set the comma separated names of user attributes to additionally query from the realm. These will be provided to the user through the created Principal's attributes map. In this map, each field value is bound to the field's name, that is, the name of the field serves as the key of the mapping.

        If set to the wildcard character, or, if the wildcard character is part of the comma separated list, all available attributes - except the password attribute (as specified by userCredCol) - are queried. The wildcard character is defined by constant USER_ATTRIBUTES_WILDCARD. It defaults to the asterisk (*) character.

        Parameters:
        userAttributes - the comma separated names of user attributes

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Description copied from interface: Realm
        Add a property change listener to this component.
        Specified by:
        addPropertyChangeListener in interface Realm
        Parameters:
        listener - The listener to add

      • authenticate

        public java.security.Principal authenticate​(java.lang.String username)
        Description copied from interface: Realm
        Try to authenticate with the specified username.
        Specified by:
        authenticate in interface Realm
        Parameters:
        username - Username of the Principal to look up
        Returns:
        the associated principal, or null if none is associated.

      • authenticate

        public java.security.Principal authenticate​(java.lang.String username,
                                            java.lang.String credentials)
        Description copied from interface: Realm
        Try to authenticate using the specified username and credentials.
        Specified by:
        authenticate in interface Realm
        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
public java.security.Principal authenticate​(java.lang.String username,
                                            java.lang.String clientDigest,
                                            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.
        Description copied from interface: Realm
        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).
        Specified by:
        authenticate in interface Realm
        Parameters:
        username - Username of the Principal to look up
        clientDigest - 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

        public java.security.Principal authenticate​(java.lang.String username,
                                            java.lang.String clientDigest,
                                            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)
        Description copied from interface: Realm
        Try to authenticate with the specified username, which matches the digest calculated using the given parameters using the method described in RFC 7616.
        Specified by:
        authenticate in interface Realm
        Parameters:
        username - Username of the Principal to look up
        clientDigest - 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

        public java.security.Principal authenticate​(java.security.cert.X509Certificate[] certs)
        Description copied from interface: Realm
        Try to authenticate using a chain of X509Certificates.
        Specified by:
        authenticate in interface Realm
        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

      • authenticate

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

      • authenticate

        public java.security.Principal authenticate​(org.ietf.jgss.GSSName gssName,
                                            org.ietf.jgss.GSSCredential gssCredential)
        Description copied from interface: GSSRealm
        Try to authenticate using a GSSName
        Specified by:
        authenticate in interface GSSRealm
        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

      • backgroundProcess

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

        The default implementation is NO-OP.

        Specified by:
        backgroundProcess in interface Realm

      • findSecurityConstraints

        public SecurityConstraint[] findSecurityConstraints​(Request request,
                                                    Context context)
        Description copied from interface: Realm
        Find the SecurityConstraints configured to guard the request URI for this request.
        Specified by:
        findSecurityConstraints in interface Realm
        Parameters:
        request - Request we are processing
        context - Context the Request is mapped to
        Returns:
        the configured SecurityConstraint, or null if there is none

      • hasResourcePermission

        public boolean hasResourcePermission​(Request request,
                                     Response response,
                                     SecurityConstraint[] constraints,
                                     Context context)
                              throws java.io.IOException
        Description copied from interface: Realm
        Perform access control based on the specified authorization constraint.
        Specified by:
        hasResourcePermission in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraints - 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

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

        This method or hasRoleInternal(Principal, String) can be overridden by Realm implementations, but the default is adequate when an instance of GenericPrincipal is used to represent authenticated Principals from this Realm.

        Specified by:
        hasRole in interface 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.

      • parseUserAttributes

        protected java.util.List<java.lang.String> parseUserAttributes​(java.lang.String userAttributes)
        Parse the specified delimiter separated attribute names and return a list of that names or null, if no attributes have been specified.

        If a wildcard character is found, return a list consisting of a single wildcard character only.

        Parameters:
        userAttributes - comma separated names of attributes to parse
        Returns:
        a list containing the parsed attribute names or null, if no attributes have been specified

      • hasRoleInternal

        protected boolean hasRoleInternal​(java.security.Principal principal,
                                  java.lang.String role)
        Check if the specified Principal has the specified security role, within the context of this Realm. This method or hasRoleInternal(Principal, String) can be overridden by Realm implementations, but the default is adequate when an instance of GenericPrincipal is used to represent authenticated Principals from this Realm.
        Parameters:
        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

        public boolean hasUserDataPermission​(Request request,
                                     Response response,
                                     SecurityConstraint[] constraints)
                              throws java.io.IOException
        Description copied from interface: Realm
        Enforce any user data constraint required by the security constraint guarding this request URI.
        Specified by:
        hasUserDataPermission in interface Realm
        Parameters:
        request - Request we are processing
        response - Response we are creating
        constraints - 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

        public void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
        Description copied from interface: Realm
        Remove a property change listener from this component.
        Specified by:
        removePropertyChangeListener in interface Realm
        Parameters:
        listener - The listener to remove

      • isAvailable

        public boolean isAvailable()
        Description copied from interface: Realm
        Return the availability of the realm for authentication.
        Specified by:
        isAvailable in interface Realm
        Returns:
        true if the realm is able to perform authentication

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hasMessageDigest

        protected boolean hasMessageDigest​(java.lang.String algorithm)

      • getDigest

        @Deprecated
protected java.lang.String getDigest​(java.lang.String username,
                                     java.lang.String realmName)
        Deprecated.
        Unused. Use getDigest(String, String, String). Will be removed in Tomcat 11.
        Return the digest associated with given principal's user name.
        Parameters:
        username - The user name
        realmName - The realm name
        Returns:
        the digest for the specified user

      • getDigest

        protected java.lang.String getDigest​(java.lang.String username,
                                     java.lang.String realmName,
                                     java.lang.String algorithm)
        Return the digest associated with given principal's user name.
        Parameters:
        username - The user name
        realmName - The realm name
        algorithm - The name of the message digest algorithm to use
        Returns:
        the digest for the specified user

      • getName

        @Deprecated
protected abstract java.lang.String getName()
        Deprecated.
        This will be removed in Tomcat 9 onwards. Use Class.getSimpleName() instead.
        Returns:
        a short name for this Realm implementation, for use in log messages.

      • getPassword

        protected abstract java.lang.String getPassword​(java.lang.String username)
        Get the password for the specified user.
        Parameters:
        username - The user name
        Returns:
        the password associated with the given principal's user name.

      • getPrincipal

        protected java.security.Principal getPrincipal​(java.security.cert.X509Certificate usercert)
        Get the principal associated with the specified certificate.
        Parameters:
        usercert - The user certificate
        Returns:
        the Principal associated with the given certificate.

      • getPrincipal

        protected abstract java.security.Principal getPrincipal​(java.lang.String username)
        Get the principal associated with the specified user.
        Parameters:
        username - The user name
        Returns:
        the Principal associated with the given user name.

      • getPrincipal

        @Deprecated
protected java.security.Principal getPrincipal​(java.lang.String username,
                                               org.ietf.jgss.GSSCredential gssCredential)
        Deprecated.
        This will be removed in Tomcat 10 onwards. Use getPrincipal(GSSName, GSSCredential) instead.
        Get the principal associated with the specified user name.
        Parameters:
        username - The user name
        gssCredential - the GSS credential of the principal
        Returns:
        the principal associated with the given user name.

      • getPrincipal

        protected java.security.Principal getPrincipal​(org.ietf.jgss.GSSName gssName,
                                               org.ietf.jgss.GSSCredential gssCredential)
        Get the principal associated with the specified GSSName.
        Parameters:
        gssName - The GSS name
        gssCredential - the GSS credential of the principal
        Returns:
        the principal associated with the given user name.

      • getServer

        protected Server getServer()
        Return the Server object that is the ultimate parent for the container with which this Realm is associated. If the server cannot be found (eg because the container hierarchy is not complete), null is returned.
        Returns:
        the Server associated with the realm

      • Digest

        @Deprecated
public static final java.lang.String Digest​(java.lang.String credentials,
                                            java.lang.String algorithm,
                                            java.lang.String encoding)
        Deprecated.
        Unused. This will be removed in Tomcat 9.
        Digest password using the algorithm specified and convert the result to a corresponding hex string.
        Parameters:
        credentials - Password or other credentials to use in authenticating this username
        algorithm - Algorithm used to do the digest
        encoding - Character encoding of the string to digest
        Returns:
        The digested credentials as a hex string or the original plain text credentials if an error occurs.

      • main

        public static void main​(java.lang.String[] args)
        Generate a stored credential string for the given password and associated parameters.

        The following parameters are supported:

        • -a - The algorithm to use to generate the stored credential. If not specified a default of SHA-512 will be used.
        • -e - The encoding to use for any byte to/from character conversion that may be necessary. If not specified, the system encoding (Charset.defaultCharset()) will be used.
        • -i - The number of iterations to use when generating the stored credential. If not specified, the default for the CredentialHandler will be used.
        • -s - The length (in bytes) of salt to generate and store as part of the credential. If not specified, the default for the CredentialHandler will be used.
        • -k - The length (in bits) of the key(s), if any, created while generating the credential. If not specified, the default for the CredentialHandler will be used.
        • -h - The fully qualified class name of the CredentialHandler to use. If not specified, the built-in handlers will be tested in turn and the first one to accept the specified algorithm will be used.

        This generation process currently supports the following CredentialHandlers, the correct one being selected based on the algorithm specified:

        Parameters:
        args - The parameters passed on the command line

      • getObjectNameKeyProperties

        public java.lang.String getObjectNameKeyProperties()
        Description copied from class: LifecycleMBeanBase
        Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.
        Specified by:
        getObjectNameKeyProperties in class LifecycleMBeanBase
        Returns:
        The string representation of the key properties component of the desired ObjectName

      • getDomainInternal

        public java.lang.String getDomainInternal()
        Description copied from class: LifecycleMBeanBase
        Method implemented by sub-classes to identify the domain in which MBeans should be registered.
        Specified by:
        getDomainInternal in class LifecycleMBeanBase
        Returns:
        The name of the domain to use to register MBeans.

      • getRealmPath

        public java.lang.String getRealmPath()

      • setRealmPath

        public void setRealmPath​(java.lang.String theRealmPath)

      • getRealmSuffix

        protected java.lang.String getRealmSuffix()

      • getRoles

        public java.lang.String[] getRoles​(java.security.Principal principal)
        Description copied from interface: Realm
        Return roles associated with given principal
        Specified by:
        getRoles in interface Realm
        Parameters:
        principal - the Principal to get the roles for.
        Returns:
        principal roles