CombinedRealm (Apache Tomcat 7.0.109 API Documentation)

java.lang.Object
- org.apache.catalina.util.LifecycleBase
- - org.apache.catalina.util.LifecycleMBeanBase
  - - org.apache.catalina.realm.RealmBase
    - - org.apache.catalina.realm.CombinedRealm

All Implemented Interfaces:

MBeanRegistration, GSSRealm, 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 and Description
`protected static String`	`name` Descriptive information about this Realm implementation.
`protected List<Realm>`	`realms` The list of Realms contained by this Realm.

Fields inherited from class org.apache.catalina.realm.RealmBase
allRolesMode, container, containerLog, digest, digestEncoding, info, md, md5Encoder, md5Helper, realmPath, sm, stripRealmForGss, support, validate, x509UsernameRetriever, x509UsernameRetrieverClassName

Fields inherited from class org.apache.catalina.util.LifecycleMBeanBase
mserver

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 and Description

CombinedRealm()

Constructors
Constructor and Description
`CombinedRealm()`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addRealm(Realm theRealm)` Add a realm to the list of realms that will be used to authenticate users.
`Principal`	`authenticate(GSSContext gssContext, boolean storeCred)` Try to authenticate using a `GSSContext`
`Principal`	`authenticate(GSSName gssName, GSSCredential gssCredential)` Try to authenticate using a `GSSName`
`Principal`	`authenticate(String username)` Return the Principal associated with the specified user name otherwise return `null`.
`Principal`	`authenticate(String username, String credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
`Principal`	`authenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String 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`.
`Principal`	`authenticate(X509Certificate[] certs)` Return the Principal associated with the specified chain of X509 client certificates.
`void`	`backgroundProcess()` Delegate the backgroundProcess call to all sub-realms.
`protected void`	`destroyInternal()` Ensure child Realms are destroyed when this Realm is destroyed.
`protected String`	`getName()` Return a short name for this Realm implementation, for use in log messages.
`protected String`	`getPassword(String username)` Return the password associated with the given principal's user name.
`protected Principal`	`getPrincipal(String username)` Return the Principal associated with the given user name.
`ObjectName[]`	`getRealms()` Return the set of Realms that this Realm is wrapping
`boolean`	`hasRole(Wrapper wrapper, Principal principal, String role)` Return `true` if the specified Principal has the specified security role, within the context of this Realm; otherwise return `false`.
`void`	`setContainer(Container container)` Set the Container with which this Realm has been associated.
`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.util.LifecycleMBeanBase
getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, 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 Detail
  - realms
```
protected List<Realm> realms
```
    The list of Realms contained by this Realm.
  - name
```
protected static final String name
```
    Descriptive information about this Realm implementation.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - CombinedRealm
```
public CombinedRealm()
```
- Method Detail
  - addRealm
```
public void addRealm(Realm theRealm)
```
    Add a realm to the list of realms that will be used to authenticate users.
  - getRealms
```
public ObjectName[] getRealms()
```
    Return the set of Realms that this Realm is wrapping
  - authenticate
```
public Principal authenticate(String username,
                     String clientDigest,
                     String nonce,
                     String nc,
                     String cnonce,
                     String qop,
                     String realmName,
                     String 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.
    
    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
    realmName - Realm name
    md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)
    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).
    
    Returns:
    the associated principal, or null if there is none.
  - authenticate
```
public Principal authenticate(String username)
```
    Return the Principal associated with the specified user name otherwise return null.
    
    Specified by:
    
    authenticate in interface Realm
    
    Overrides:
    
    authenticate in class RealmBase
    
    Parameters:
    username - User name of the Principal to look up
    
    Returns:
    the associated principal, or null if none is associated.
  - authenticate
```
public Principal authenticate(String username,
                     String credentials)
```
    Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
    
    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)
```
    Set the Container with which this Realm has been associated.
    
    Specified by:
    
    setContainer in interface Realm
    
    Overrides:
    
    setContainer in class RealmBase
    
    Parameters:
    container - The associated Container
  - 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().
    
    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
```
    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)
```
    Return the Principal associated with the specified chain of X509 client certificates. If there is none, return null.
    
    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)
```
    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)
```
    Try to authenticate using a GSSName
    
    Specified by:
    
    authenticate in interface GSSRealm
    
    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)
```
    Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false. This method 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.
  - getName
```
protected String getName()
```
    Description copied from class: RealmBase
    
    Return a short name for this Realm implementation, for use in log messages.
    
    Specified by:
    
    getName in class RealmBase
  - getPassword
```
protected String getPassword(String username)
```
    Description copied from class: RealmBase
    
    Return the password associated with the given principal's user name.
    
    Specified by:
    
    getPassword in class RealmBase
  - getPrincipal
```
protected Principal getPrincipal(String username)
```
    Description copied from class: RealmBase
    
    Return the Principal associated with the given user name.
    
    Specified by:
    
    getPrincipal in class RealmBase

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

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 Detail

realms

name

Constructor Detail

CombinedRealm

Method Detail

addRealm

getRealms

authenticate

authenticate

authenticate

setContainer

startInternal

stopInternal

destroyInternal

backgroundProcess

authenticate

authenticate

authenticate

hasRole

getName

getPassword

getPrincipal