Package org.apache.catalina.realm

Class RealmBase

java.lang.Object

org.apache.catalina.util.LifecycleBase

org.apache.catalina.util.LifecycleMBeanBase

org.apache.catalina.realm.RealmBase

All Implemented Interfaces:

MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm

Direct Known Subclasses:

AuthenticatedUserRealm, CombinedRealm, DataSourceRealm, JAASRealm, JNDIRealm, MemoryRealm, NullRealm, UserDatabaseRealm

public abstract class RealmBase
extends LifecycleMBeanBase
implements Realm

Simple implementation of Realm that reads an XML file to configure the valid users, passwords, and roles. The file format (and default file location) are identical to those currently supported by Tomcat 3.X.

Author:

Craig R. McClanahan

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	RealmBase.AllRolesMode

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

Lifecycle.SingleUse

Field Summary

Fields

Modifier and Type	Field	Description
protected RealmBase.AllRolesMode	allRolesMode	The all role mode.
protected Container	container	The Container with which this Realm is associated.
protected Log	containerLog	Container log
protected String	realmPath
protected static final StringManager	sm	The string manager for this package.
protected boolean	stripRealmForGss	When processing users authenticated via the GSS-API, should any "@..." be stripped from the end of the user name?
protected final PropertyChangeSupport	support	The property change support for this component.
protected static final String	USER_ATTRIBUTES_DELIMITER	The character used for delimiting user attribute names.
protected static final String	USER_ATTRIBUTES_WILDCARD	The character used as wildcard in user attribute lists.
protected String	userAttributes	The comma separated names of user attributes to additionally query from the realm.
protected List<String>	userAttributesList	The list of user attributes to additionally query from the realm.
protected boolean	validate	Should we validate client certificate chains when they are presented?
protected X509UsernameRetriever	x509UsernameRetriever	The object that will extract user names from X509 client certificates.
protected String	x509UsernameRetrieverClassName	The name of the class to use for retrieving user names from X509 certificates.

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors

Constructor	Description
RealmBase()

Method Summary

Modifier and Type	Method	Description
void	addPropertyChangeListener(PropertyChangeListener listener)	Add a property change listener to this component.
Principal	authenticate(String username)	Try to authenticate with the specified username.
Principal	authenticate(String username, String credentials)	Try to authenticate using the specified username and credentials.
Principal	authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realm, String digestA2, 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.
Principal	authenticate(X509Certificate[] certs)	Try to authenticate using a chain of X509Certificates.
Principal	authenticate(GSSContext gssContext, boolean storeCred)	Try to authenticate using a GSSContext.
Principal	authenticate(GSSName gssName, 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.
String	getAllRolesMode()	Return the all roles mode.
Container	getContainer()	Get the Container with which this instance is associated.
CredentialHandler	getCredentialHandler()
protected String	getDigest(String username, String realmName, String algorithm)	Return the digest associated with given principal's user name.
String	getDomainInternal()	Method implemented by sub-classes to identify the domain in which MBeans should be registered.
String	getObjectNameKeyProperties()	Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.
protected abstract String	getPassword(String username)	Get the password for the specified user.
protected abstract Principal	getPrincipal(String username)	Get the principal associated with the specified user.
protected Principal	getPrincipal(X509Certificate usercert)	Get the principal associated with the specified certificate.
protected Principal	getPrincipal(GSSName gssName, GSSCredential gssCredential)	Get the principal associated with the specified GSSName.
protected Principal	getPrincipal(GSSName gssName, GSSCredential gssCredential, GSSContext gssContext)	Get the principal associated with the specified GSSName.
String	getRealmPath()
protected String	getRealmSuffix()
protected Server	getServer()	Return the Server object that is the ultimate parent for the container with which this Realm is associated.
int	getTransportGuaranteeRedirectStatus()
String	getUserAttributes()
boolean	getValidate()	Return the "validate certificate chains" flag.
String	getX509UsernameRetrieverClassName()	Gets the name of the class that will be used to extract user names from X509 client certificates.
protected boolean	hasMessageDigest(String algorithm)
boolean	hasResourcePermission(Request request, Response response, SecurityConstraint[] constraints, Context context)	Perform access control based on the specified authorization constraint.
boolean	hasRole(Wrapper wrapper, Principal principal, String role)	Check if the specified Principal has the specified security role, within the context of this Realm.
protected boolean	hasRoleInternal(Principal principal, 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[] constraints)	Enforce any user data constraint required by the security constraint guarding this request URI.
protected void	initInternal()	Sub-classes implement this method to perform any instance initialisation required.
boolean	isStripRealmForGss()
static void	main(String[] args)	Generate a stored credential string for the given password and associated parameters.
protected List<String>	parseUserAttributes(String userAttributes)	Parse the specified delimiter separated attribute names and return a list of that names or null, if no attributes have been specified.
void	removePropertyChangeListener(PropertyChangeListener listener)	Remove a property change listener from this component.
void	setAllRolesMode(String allRolesMode)	Set the all roles mode.
void	setContainer(Container container)	Set the Container with which this instance is associated.
void	setCredentialHandler(CredentialHandler credentialHandler)	Set the CredentialHandler to be used by this Realm.
void	setRealmPath(String theRealmPath)
void	setStripRealmForGss(boolean stripRealmForGss)
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.
void	setUserAttributes(String userAttributes)	Set the comma separated names of user attributes to additionally query from the realm.
void	setValidate(boolean validate)	Set the "validate certificate chains" flag.
void	setX509UsernameRetrieverClassName(String className)	Sets the name of the class that will be used to extract user names from X509 client certificates.
protected void	startInternal()	Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
protected void	stopInternal()	Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().
String	toString()

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.catalina.Realm

isAvailable

Field Details

USER_ATTRIBUTES_DELIMITER

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

allRolesMode

protected RealmBase.AllRolesMode allRolesMode

The all role mode.

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 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 List<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 String realmPath

Constructor Details

RealmBase

public RealmBase()

Method Details

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

getCredentialHandler

public CredentialHandler getCredentialHandler()

Specified by:

getCredentialHandler in interface Realm

Returns:

the CredentialHandler configured for this Realm.

setCredentialHandler

public void setCredentialHandler(CredentialHandler credentialHandler)

Description copied from interface: Realm

Set the CredentialHandler to be used by this Realm.

Specified by:

setCredentialHandler in interface Realm

Parameters:

credentialHandler - the CredentialHandler to use

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 String getAllRolesMode()

Return the all roles mode.

Returns:

A string representation of the current all roles mode

setAllRolesMode

public void setAllRolesMode(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 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(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 String getUserAttributes()

Returns:

the comma separated names of user attributes to additionally query from realm

setUserAttributes

public void setUserAttributes(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(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 Principal authenticate(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 Principal authenticate(String username,
 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

public Principal authenticate(String username,
 String clientDigest,
 String nonce,
 String nc,
 String cnonce,
 String qop,
 String realm,
 String digestA2,
 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 Principal authenticate(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 Principal authenticate(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 Principal authenticate(GSSName gssName,
 GSSCredential gssCredential)

Description copied from interface: Realm

Try to authenticate using a GSSName.

Specified by:

authenticate in interface Realm

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 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:

IOException - if an input/output error occurs

hasRole

public boolean hasRole(Wrapper wrapper,
 Principal principal,
 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 List<String> parseUserAttributes(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(Principal principal,
 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 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:

IOException - if an input/output error occurs

removePropertyChangeListener

public void removePropertyChangeListener(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

initInternal

protected void initInternal()
                     throws LifecycleException

Description copied from class: LifecycleBase

Sub-classes implement this method to perform any instance initialisation required.

Overrides:

initInternal in class LifecycleMBeanBase

Throws:

LifecycleException - If the initialisation fails

startInternal

protected void startInternal()
                      throws LifecycleException

Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().

Specified by:

startInternal in class LifecycleBase

Throws:

LifecycleException - if this component detects a fatal error that prevents this component from being used

stopInternal

protected void stopInternal()
                     throws LifecycleException

Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().

Specified by:

stopInternal in class LifecycleBase

Throws:

LifecycleException - if this component detects a fatal error that needs to be reported

toString

public String toString()

Overrides:

toString in class Object

hasMessageDigest

protected boolean hasMessageDigest(String algorithm)

getDigest

protected String getDigest(String username,
 String realmName,
 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

getPassword

protected abstract String getPassword(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 Principal getPrincipal(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 Principal getPrincipal(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

protected Principal getPrincipal(GSSName gssName,
 GSSCredential gssCredential,
 GSSContext gssContext)

Get the principal associated with the specified GSSName.

Parameters:

gssName - The GSS name

gssCredential - the GSS credential of the principal

gssContext - the established GSS context

Returns:

the principal associated with the given user name.

getPrincipal

protected Principal getPrincipal(GSSName gssName,
 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

main

public static void main(String[] args)
                 throws IOException

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.
• -f - The name of the file that contains passwords to encode. Each line in the file should contain only one password. Using this option ignores other password input.

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

• MessageDigestCredentialHandler
• SecretKeyCredentialHandler

Parameters:

args - The parameters passed on the command line

Throws:

IOException - If an error occurs reading the password file

getObjectNameKeyProperties

public 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 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 String getRealmPath()

setRealmPath

public void setRealmPath(String theRealmPath)

getRealmSuffix

protected String getRealmSuffix()