org.apache.catalina

Interface Realm

All Known Implementing Classes:

JAASRealm, RealmAdapter, RealmBase

@Contract
 @PerLookup
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.

Version:

$Revision: 1.6 $ $Date: 2007/04/18 17:27:22 $

Author:

Craig R. McClanahan

Field Summary

Fields

Modifier and Type	Field and Description
static int	AUTHENTICATE_NEEDED Flag indicating authentication is needed for current request.
static int	AUTHENTICATE_NOT_NEEDED Flag indicating authentication is not needed for current request.
static int	AUTHENTICATED_NOT_AUTHORIZED Flag indicating the user has been authenticated but been denied access to the requested resource.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener listener) Add a property change listener to this component.
Principal	authenticate(javax.servlet.http.HttpServletRequest hreq) Does digest authentication and returns the Principal associated with the username in the HTTP header.
Principal	authenticate(String username, char[] credentials) Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principal	authenticate(String username, char[] digest, String nonce, String nc, String cnonce, String qop, String realm, char[] 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.
SecurityConstraint[]	findSecurityConstraints(HttpRequest request, Context context) Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.
SecurityConstraint[]	findSecurityConstraints(String uri, String method, Context context) Gets the security constraints configured by the given context for the given request URI and method.
String	getAlternateAuthType(HttpRequest req) Return an alternate auth type from the request if available.
Principal	getAlternatePrincipal(HttpRequest req) Return an alternate principal from the request if available.
Container	getContainer() Return the Container with which this Realm has been associated.
String	getInfo() Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.
String	getRealmName() Returns the name of the associated realm.
boolean	hasResourcePermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint, Context context) Perform access control based on the specified authorization constraint.
boolean	hasRole(HttpRequest request, HttpResponse response, Principal principal, String role) Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
boolean	hasRole(Principal principal, String role) Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.
boolean	hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraint) Enforce any user data constraint required by the security constraint guarding this request URI.
boolean	hasUserDataPermission(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints, String uri, String method) Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied.
boolean	invokeAuthenticateDelegate(HttpRequest request, HttpResponse response, Context context, Authenticator authenticator, boolean calledFromAuthenticate) Authenticates the user making this request, based on the specified login configuration.
boolean	invokePostAuthenticateDelegate(HttpRequest request, HttpResponse response, Context context) Post authentication for given request and response.
boolean	isSecurityExtensionEnabled(javax.servlet.ServletContext servletContext) Returns whether the specified ServletContext indicates that security extension is enabled.
void	logout(HttpRequest hreq) Logs out.
int	preAuthenticateCheck(HttpRequest request, HttpResponse response, SecurityConstraint[] constraints, boolean disableProxyCaching, boolean securePagesWithPragma, boolean ssoEnabled) Checks whether or not authentication is needed.
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	setRealmName(String name, String authMethod) Set the name of the associated realm.

Field Detail

AUTHENTICATE_NEEDED

static final int AUTHENTICATE_NEEDED

Flag indicating authentication is needed for current request. Used by preAuthenticateCheck method.

See Also:

Constant Field Values

AUTHENTICATE_NOT_NEEDED

static final int AUTHENTICATE_NOT_NEEDED

Flag indicating authentication is not needed for current request. Used by preAuthenticateCheck method.

See Also:

Constant Field Values

AUTHENTICATED_NOT_AUTHORIZED

static final int AUTHENTICATED_NOT_AUTHORIZED

Flag indicating the user has been authenticated but been denied access to the requested resource.

See Also:

Constant Field Values

Method Detail

getContainer

Container getContainer()

Return 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

getInfo

String getInfo()

Return descriptive information about this Realm implementation and the corresponding version number, in the format <description>/<version>.

addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Add a property change listener to this component.

Parameters:

listener - The listener to add

authenticate

Principal authenticate(String username,
                       char[] credentials)

Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.

Parameters:

username - Username of the Principal to look up

credentials - Password or other credentials to use in authenticating this username

authenticate

Principal authenticate(String username,
                       char[] digest,
                       String nonce,
                       String nc,
                       String cnonce,
                       String qop,
                       String realm,
                       char[] 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.

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

realm - Realm name

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

authenticate

Principal authenticate(X509Certificate[] certs)

Return the Principal associated with the specified chain of X509 client certificates. If there is none, return null.

Parameters:

certs - Array of client certificates, with the first one in the array being the certificate of the client itself.

authenticate

Principal authenticate(javax.servlet.http.HttpServletRequest hreq)

Does digest authentication and returns the Principal associated with the username in the HTTP header.

Parameters:

hreq - HTTP servlet request.

findSecurityConstraints

SecurityConstraint[] findSecurityConstraints(HttpRequest request,
                                             Context context)

Return the SecurityConstraints configured to guard the request URI for this request, or null if there is no such constraint.

Parameters:

request - Request we are processing

findSecurityConstraints

SecurityConstraint[] findSecurityConstraints(String uri,
                                             String method,
                                             Context context)

Gets the security constraints configured by the given context for the given request URI and method.

Parameters:

uri - the request URI

method - the request method

context - the context

Returns:

the security constraints configured by the given context for the given request URI and method, or null

hasResourcePermission

boolean hasResourcePermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint,
                              Context context)
                       throws IOException

Perform access control based on the specified authorization constraint. Return true if this constraint is satisfied and processing should continue, or false otherwise.

Parameters:

request - Request we are processing

response - Response we are creating

constraint - Security constraint we are enforcing

context - Context to which client of this class is attached.

Throws:

IOException - if an input/output error occurs

hasRole

boolean hasRole(Principal principal,
                String role)

Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.

Parameters:

principal - Principal for whom the role is to be checked

role - Security role to be checked

hasRole

boolean hasRole(HttpRequest request,
                HttpResponse response,
                Principal principal,
                String role)

Return true if the specified Principal has the specified security role, within the context of this Realm; otherwise return false.

Parameters:

request - Request we are processing

response - Response we are creating

principal - Principal for whom the role is to be checked

role - Security role to be checked

preAuthenticateCheck

int preAuthenticateCheck(HttpRequest request,
                         HttpResponse response,
                         SecurityConstraint[] constraints,
                         boolean disableProxyCaching,
                         boolean securePagesWithPragma,
                         boolean ssoEnabled)
                  throws IOException

Checks whether or not authentication is needed. Returns an int, one of AUTHENTICATE_NOT_NEEDED, AUTHENTICATE_NEEDED, or AUTHENTICATED_NOT_AUTHORIZED.

Parameters:

request - Request we are processing

response - Response we are creating

constraints - Security constraint we are enforcing

disableProxyCaching - whether or not to disable proxy caching for protected resources.

securePagesWithPragma - true if we add headers which are incompatible with downloading office documents in IE under SSL but which fix a caching problem in Mozill

ssoEnabled - true if sso is enabled

Throws:

IOException - if an input/output error occurs

invokeAuthenticateDelegate

boolean invokeAuthenticateDelegate(HttpRequest request,
                                   HttpResponse response,
                                   Context context,
                                   Authenticator authenticator,
                                   boolean calledFromAuthenticate)
                            throws IOException

Authenticates the user making this request, based on the specified login configuration. Return true if any specified requirements have been satisfied, or false if we have created a response challenge already.

Parameters:

request - Request we are processing

response - Response we are creating

context - The Context to which client of this class is attached.

authenticator - the current authenticator.

calledFromAuthenticate - true if the call originates from HttpServletRequest.authenticate

Throws:

IOException - if an input/output error occurs

invokePostAuthenticateDelegate

boolean invokePostAuthenticateDelegate(HttpRequest request,
                                       HttpResponse response,
                                       Context context)
                                throws IOException

Post authentication for given request and response.

Parameters:

request - Request we are processing

response - Response we are creating

context - The Context to which client of this class is attached.

Throws:

IOException - if an input/output error occurs

hasUserDataPermission

boolean hasUserDataPermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraint)
                       throws IOException

Enforce any user data constraint required by the security constraint guarding this request URI. Return true if this constraint was not violated and processing should continue, or false if we have created a response already.

Parameters:

request - Request we are processing

response - Response we are creating

constraint - Security constraint being checked

Throws:

IOException - if an input/output error occurs

hasUserDataPermission

boolean hasUserDataPermission(HttpRequest request,
                              HttpResponse response,
                              SecurityConstraint[] constraints,
                              String uri,
                              String method)
                       throws IOException

Checks if the given request URI and method are the target of any user-data-constraint with a transport-guarantee of CONFIDENTIAL, and whether any such constraint is already satisfied. If uri and method are null, then the URI and method of the given request are checked. If a user-data-constraint exists that is not satisfied, then the given request will be redirected to HTTPS.

Parameters:

request - the request that may be redirected

response - the response that may be redirected

constraints - the security constraints to check against

uri - the request URI (minus the context path) to check

method - the request method to check

Returns:

true if the request URI and method are not the target of any unsatisfied user-data-constraint with a transport-guarantee of CONFIDENTIAL, and false if they are (in which case the given request will have been redirected to HTTPS)

Throws:

IOException

removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Remove a property change listener from this component.

Parameters:

listener - The listener to remove

getAlternatePrincipal

Principal getAlternatePrincipal(HttpRequest req)

Return an alternate principal from the request if available.

Parameters:

req - The request object.

Returns:

Alternate principal or null.

getAlternateAuthType

String getAlternateAuthType(HttpRequest req)

Return an alternate auth type from the request if available.

Parameters:

req - The request object.

Returns:

Alternate auth type or null.

setRealmName

void setRealmName(String name,
                  String authMethod)

Set the name of the associated realm.

Parameters:

name - the name of the realm.

getRealmName

String getRealmName()

Returns the name of the associated realm.

Returns:

realm name or null if not set.

isSecurityExtensionEnabled

boolean isSecurityExtensionEnabled(javax.servlet.ServletContext servletContext)

Returns whether the specified ServletContext indicates that security extension is enabled.

Parameters:

servletContext - the ServletContext

Returns:

true if security extension is enabled; false otherwise

logout

void logout(HttpRequest hreq)

Logs out.

Parameters:

hreq - the HttpRequest