org.apache.catalina

Interface Realm

All Known Implementing Classes:

CombinedRealm, DataSourceRealm, JAASMemoryLoginModule, JAASRealm, JDBCRealm, JNDIRealm, LockOutRealm, MemoryRealm, NullRealm, RealmBase, UserDatabaseRealm

public interface Realm

A Realm is a read-only facade for an underlying security realm used to authenticate individual users, and identify the security roles associated with those users. Realms can be attached at any Container level, but will typically only be attached to a Context, or higher level, Container.

Author:

Craig R. McClanahan

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener listener) Add a property change listener to this component.
Principal	authenticate(GSSContext gssContext, boolean storeCreds) Try to authenticate using a GSSContext
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 digest, String nonce, String nc, String cnonce, String qop, String realm, String md5a2) 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).
Principal	authenticate(X509Certificate[] certs) Try to authenticate using X509Certificates
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.
Container	getContainer()
CredentialHandler	getCredentialHandler()
String[]	getRoles(Principal principal) Return roles associated with given principal
boolean	hasResourcePermission(Request request, Response response, SecurityConstraint[] constraint, 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.
boolean	hasUserDataPermission(Request request, Response response, SecurityConstraint[] constraint) Enforce any user data constraint required by the security constraint guarding this request URI.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a property change listener from this component.
void	setContainer(Container container) Set the Container with which this Realm has been associated.
void	setCredentialHandler(CredentialHandler credentialHandler) Set the CredentialHandler to be used by this Realm.

Method Detail

getContainer

Container getContainer()

Returns:

the Container with which this Realm has been associated.

setContainer

void setContainer(Container container)

Set the Container with which this Realm has been associated.

Parameters:

container - The associated Container

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(PropertyChangeListener listener)

Add a property change listener to this component.

Parameters:

listener - The listener to add

authenticate

Principal authenticate(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

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

Principal authenticate(String username,
                       String digest,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String realm,
                       String md5a2)

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

md5a2 - Second MD5 digest used to calculate the digest : MD5(Method + ":" + uri)

Returns:

the associated principal, or null if there is none.

authenticate

Principal authenticate(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

Principal authenticate(X509Certificate[] certs)

Try to authenticate using 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 for this request

Returns:

the configured SecurityConstraint, of null if there is none

hasResourcePermission

boolean hasResourcePermission(Request request,
                              Response response,
                              SecurityConstraint[] constraint,
                              Context context)
                       throws 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:

IOException - if an input/output error occurs

hasRole

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

IOException - if an input/output error occurs

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Remove a property change listener from this component.

Parameters:

listener - The listener to remove

getRoles

String[] getRoles(Principal principal)

Return roles associated with given principal

Parameters:

principal - the Principal to get the roles for.

Returns:

principal roles