org.apache.catalina.realm.CombinedRealm

All Implemented Interfaces:: MBeanRegistration, Contained, JmxEnabled, Lifecycle, Realm

Direct Known Subclasses:: LockOutRealm

public class CombinedRealm extends RealmBase

Realm implementation that contains one or more realms. Authentication is attempted for each realm in the order they were configured. If any realm authenticates the user then the authentication succeeds. When combining realms usernames should be unique across all combined realms.

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase
RealmBase.AllRolesMode

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

Fields

Modifier and Type

Field

Description

protected final List<Realm>

realms

The list of Realms contained by this Realm.

Fields inherited from class org.apache.catalina.realm.RealmBase
allRolesMode, container, containerLog, realmPath, sm, stripRealmForGss, support, USER_ATTRIBUTES_DELIMITER, USER_ATTRIBUTES_WILDCARD, userAttributes, userAttributesList, validate, x509UsernameRetriever, x509UsernameRetrieverClassName

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

CombinedRealm()
Method Summary

Modifier and Type

Method

Description

void

addRealm(Realm theRealm)

Add a realm to the list of realms that will be used to authenticate users.

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 realmName, 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()

Delegate the backgroundProcess call to all sub-realms.

protected void

destroyInternal()

Ensure child Realms are destroyed when this Realm is destroyed.

Realm[]

getNestedRealms()

protected String

getPassword(String username)

Get the password for the specified user.

protected Principal

getPrincipal(String username)

Get the principal associated with the specified user.

ObjectName[]

getRealms()

boolean

hasRole(Wrapper wrapper, Principal principal, String role)

Check if the specified Principal has the specified security role, within the context of this Realm.

boolean

isAvailable()

Return the availability of the realm for authentication.

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.

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().

Methods inherited from class org.apache.catalina.realm.RealmBase
addPropertyChangeListener, authenticate, findSecurityConstraints, getAllRolesMode, getContainer, getCredentialHandler, getDigest, getDigest, getDomainInternal, getObjectNameKeyProperties, getPrincipal, getPrincipal, getPrincipal, getRealmPath, getRealmSuffix, getServer, getTransportGuaranteeRedirectStatus, getUserAttributes, getValidate, getX509UsernameRetrieverClassName, hasMessageDigest, hasResourcePermission, hasRoleInternal, hasUserDataPermission, initInternal, isStripRealmForGss, main, parseUserAttributes, removePropertyChangeListener, setAllRolesMode, setRealmPath, setStripRealmForGss, setTransportGuaranteeRedirectStatus, setUserAttributes, setValidate, setX509UsernameRetrieverClassName, toString

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase
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

Field Details
- realms
  
  protected final List<Realm> realms
  
  The list of Realms contained by this Realm.
Constructor Details
- CombinedRealm
  
  public CombinedRealm()
Method Details
- addRealm
  
  public void addRealm(Realm theRealm)
  
  Add a realm to the list of realms that will be used to authenticate users.
  
  Parameters:
  
  theRealm - realm which should be wrapped by the combined realm
- getRealms
  
  public ObjectName[] getRealms()
  
  Returns:
  
  the set of Realms that this Realm is wrapping
- getNestedRealms
  
  public Realm[] getNestedRealms()
  
  Returns:
  
  the list of Realms contained by this Realm.
- authenticate
  
  public Principal authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, 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.
  The default implementation calls Realm.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.
  
  Specified by:
  
  authenticate in interface Realm
  
  Overrides:
  
  authenticate in class RealmBase
  
  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).
  
  realmName - 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(String username)
  
  Description copied from interface: Realm
  
  Try to authenticate with the specified username.
  
  Specified by:
  
  authenticate in interface Realm
  
  Overrides:
  
  authenticate in class RealmBase
  
  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
  
  Overrides:
  
  authenticate in class RealmBase
  
  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
- 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
  
  Overrides:
  
  setContainer in class RealmBase
  
  Parameters:
  
  container - The Container instance with which this instance is to be associated, or null to disassociate this instance from any Container
- startInternal
  
  protected void startInternal() throws LifecycleException
  
  Description copied from class: RealmBase
  
  Prepare for the beginning of active use of the public methods of this component and implement the requirements of LifecycleBase.startInternal().
  
  Overrides:
  
  startInternal in class RealmBase
  
  Throws:
  
  LifecycleException - if this component detects a fatal error that prevents this component from being used
- stopInternal
  
  protected void stopInternal() throws LifecycleException
  
  Description copied from class: RealmBase
  
  Gracefully terminate the active use of the public methods of this component and implement the requirements of LifecycleBase.stopInternal().
  
  Overrides:
  
  stopInternal in class RealmBase
  
  Throws:
  
  LifecycleException - if this component detects a fatal error that needs to be reported
- destroyInternal
  
  protected void destroyInternal() throws LifecycleException
  
  Ensure child Realms are destroyed when this Realm is destroyed.
  
  Overrides:
  
  destroyInternal in class LifecycleMBeanBase
  
  Throws:
  
  LifecycleException - If the destruction fails
- backgroundProcess
  
  public void backgroundProcess()
  
  Delegate the backgroundProcess call to all sub-realms.
  
  Specified by:
  
  backgroundProcess in interface Realm
  
  Overrides:
  
  backgroundProcess in class RealmBase
- 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
  
  Overrides:
  
  authenticate in class RealmBase
  
  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
  
  Overrides:
  
  authenticate in class RealmBase
  
  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
  
  Overrides:
  
  authenticate in class RealmBase
  
  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
- hasRole
  
  public boolean hasRole(Wrapper wrapper, Principal principal, String role)
  
  Description copied from class: RealmBase
  
  Check if the specified Principal has the specified security role, within the context of this Realm.
  This method or RealmBase.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
  
  Overrides:
  
  hasRole in class RealmBase
  
  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.
- getPassword
  
  protected String getPassword(String username)
  
  Description copied from class: RealmBase
  
  Get the password for the specified user.
  
  Specified by:
  
  getPassword in class RealmBase
  
  Parameters:
  
  username - The user name
  
  Returns:
  
  the password associated with the given principal's user name.
- getPrincipal
  
  protected Principal getPrincipal(String username)
  
  Description copied from class: RealmBase
  
  Get the principal associated with the specified user.
  
  Specified by:
  
  getPrincipal in class RealmBase
  
  Parameters:
  
  username - The user name
  
  Returns:
  
  the Principal associated with the given user name.
- isAvailable
  
  public boolean isAvailable()
  
  Description copied from interface: Realm
  
  Return the availability of the realm for authentication.
  
  Returns:
  
  true if the realm is able to perform authentication
- 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
  
  Overrides:
  
  setCredentialHandler in class RealmBase
  
  Parameters:
  
  credentialHandler - the CredentialHandler to use

Class CombinedRealm

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.realm.RealmBase

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

Field Summary

Fields inherited from class org.apache.catalina.realm.RealmBase

Fields inherited from interface org.apache.catalina.Lifecycle

Constructor Summary

Method Summary

Methods inherited from class org.apache.catalina.realm.RealmBase

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

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

Methods inherited from class java.lang.Object

Field Details

realms

Constructor Details

CombinedRealm

Method Details

addRealm

getRealms

getNestedRealms

authenticate

authenticate

authenticate

setContainer

startInternal

stopInternal

destroyInternal

backgroundProcess

authenticate

authenticate

authenticate

hasRole

getPassword

getPrincipal

isAvailable

setCredentialHandler