org.apache.catalina.realm

Class JAASRealm

public class JAASRealm extends RealmBase

Implmentation of Realm that authenticates users via the Java Authentication and Authorization Service (JAAS). JAAS support requires either JDK 1.4 (which includes it as part of the standard platform) or JDK 1.3 (with the plug-in jaas.jar file).

The value configured for the appName property is passed to the javax.security.auth.login.LoginContext constructor, to specify the application name used to select the set of relevant LoginModules required.

The JAAS Specification describes the result of a successful login as a javax.security.auth.Subject instance, which can contain zero or more java.security.Principal objects in the return value of the Subject.getPrincipals() method. However, it provides no guidance on how to distinguish Principals that describe the individual user (and are thus appropriate to return as the value of request.getUserPrincipal() in a web application) from the Principal(s) that describe the authorized roles for this user. To maintain as much independence as possible from the underlying LoginMethod implementation executed by JAAS, the following policy is implemented by this Realm:

Version: $Revision: 892553 $ $Date: 2009-12-20 03:32:53 +0100 (Sun, 20 Dec 2009) $

Author: Craig R. McClanahan Yoav Shapira

Field Summary
protected StringappName
The application name passed to the JAAS LoginContext, which uses it to select the set of relevant LoginModules.
protected static Stringinfo
Descriptive information about this Realm implementation.
protected static Stringname
Descriptive information about this Realm implementation.
protected List<String>roleClasses
The list of role class names, split out for easy processing.
protected StringroleClassNames
Comma-delimited list of java.security.Principal classes that represent security roles.
protected static StringManagersm
The string manager for this package.
protected booleanuseContextClassLoader
Whether to use context ClassLoader or default ClassLoader.
protected List<String>userClasses
The set of user class names, split out for easy processing.
protected StringuserClassNames
Comma-delimited list of java.security.Principal classes that represent individual users.
Method Summary
Principalauthenticate(String username, String credentials)
Return the Principal associated with the specified username and credentials, if there is one; otherwise return null.
Principalauthenticate(String username, String clientDigest, String nonce, String nc, String cnonce, String qop, String realmName, String md5a2)
Return the Principal associated with the specified username and digest, if there is one; otherwise return null.
protected Principalauthenticate(String username, CallbackHandler callbackHandler)
Perform the actual JAAS authentication
protected PrincipalcreatePrincipal(String username, Subject subject)
protected PrincipalcreatePrincipal(String username, Subject subject, LoginContext loginContext)
Identify and return a java.security.Principal instance representing the authenticated user for the specified Subject.
StringgetAppName()
getter for the appName member variable
protected StringgetName()
Return a short name for this Realm implementation.
protected StringgetPassword(String username)
Return the password associated with the given principal's user name.
protected PrincipalgetPrincipal(String username)
Return the Principal associated with the given user name.
StringgetRoleClassNames()
StringgetUserClassNames()
booleanisUseContextClassLoader()
Returns whether to use the context or default ClassLoader.
protected StringmakeLegalForJAAS(String src)
Ensure the given name is legal for JAAS configuration.
protected voidparseClassNames(String classNamesString, List<String> classNamesList)
Parses a comma-delimited list of class names, and store the class names in the provided List.
voidsetAppName(String name)
setter for the appName member variable
voidsetContainer(Container container)
voidsetRoleClassNames(String roleClassNames)
Sets the list of comma-delimited classes that represent roles.
voidsetUseContextClassLoader(boolean useContext)
Sets whether to use the context or default ClassLoader.
voidsetUserClassNames(String userClassNames)
Sets the list of comma-delimited classes that represent individual users.
voidstart()
Prepare for active use of the public methods of this Component.
voidstop()
Gracefully shut down active use of the public methods of this Component.

Field Detail

appName

protected String appName
The application name passed to the JAAS LoginContext, which uses it to select the set of relevant LoginModules.

info

protected static final String info
Descriptive information about this Realm implementation.

name

protected static final String name
Descriptive information about this Realm implementation.

roleClasses

protected List<String> roleClasses
The list of role class names, split out for easy processing.

roleClassNames

protected String roleClassNames
Comma-delimited list of java.security.Principal classes that represent security roles.

sm

protected static final StringManager sm
The string manager for this package.

useContextClassLoader

protected boolean useContextClassLoader
Whether to use context ClassLoader or default ClassLoader. True means use context ClassLoader, and True is the default value.

userClasses

protected List<String> userClasses
The set of user class names, split out for easy processing.

userClassNames

protected String userClassNames
Comma-delimited list of java.security.Principal classes that represent individual users.

Method Detail

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.

Parameters: username Username of the Principal to look up credentials Password or other credentials to use in authenticating this username

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 and digest, if there is one; otherwise return null.

Parameters: username Username of the Principal to look up clientDigest Digest to use in authenticating this username nonce Server generated nonce nc Nonce count cnonce Client generated nonce qop Quality of protection aplied to the message realmName Realm name md5a2 Second MD5 digest used to calculate the digest MD5(Method + ":" + uri)

authenticate

protected Principal authenticate(String username, CallbackHandler callbackHandler)
Perform the actual JAAS authentication

createPrincipal

protected Principal createPrincipal(String username, Subject subject)

Deprecated: Use JAASRealm

createPrincipal

protected Principal createPrincipal(String username, Subject subject, LoginContext loginContext)
Identify and return a java.security.Principal instance representing the authenticated user for the specified Subject. The Principal is constructed by scanning the list of Principals returned by the JAASLoginModule. The first Principal object that matches one of the class names supplied as a "user class" is the user Principal. This object is returned to the caller. Any remaining principal objects returned by the LoginModules are mapped to roles, but only if their respective classes match one of the "role class" classes. If a user Principal cannot be constructed, return null.

Parameters: subject The Subject representing the logged-in user loginContext Associated with the Principal so LoginContext#logout() can be called later

getAppName

public String getAppName()
getter for the appName member variable

getName

protected String getName()
Return a short name for this Realm implementation.

getPassword

protected String getPassword(String username)
Return the password associated with the given principal's user name. This always returns null as the JAASRealm has no way of obtaining this information.

getPrincipal

protected Principal getPrincipal(String username)
Return the Principal associated with the given user name.

getRoleClassNames

public String getRoleClassNames()

getUserClassNames

public String getUserClassNames()

isUseContextClassLoader

public boolean isUseContextClassLoader()
Returns whether to use the context or default ClassLoader. True means to use the context ClassLoader.

Returns: The value of useContextClassLoader

makeLegalForJAAS

protected String makeLegalForJAAS(String src)
Ensure the given name is legal for JAAS configuration. Added for Bugzilla 30869, made protected for easy customization in case my implementation is insufficient, which I think is very likely.

Parameters: src The name to validate

Returns: A string that's a valid JAAS realm name

parseClassNames

protected void parseClassNames(String classNamesString, List<String> classNamesList)
Parses a comma-delimited list of class names, and store the class names in the provided List. Each class must implement java.security.Principal.

Parameters: classNamesString a comma-delimited list of fully qualified class names. classNamesList the list in which the class names will be stored. The list is cleared before being populated.

setAppName

public void setAppName(String name)

Deprecated: JAAS should use the Engine (domain) name and webpp/host overrides

setter for the appName member variable

setContainer

public void setContainer(Container container)

setRoleClassNames

public void setRoleClassNames(String roleClassNames)
Sets the list of comma-delimited classes that represent roles. The classes in the list must implement java.security.Principal. The supplied list of classes will be parsed when start is called.

setUseContextClassLoader

public void setUseContextClassLoader(boolean useContext)
Sets whether to use the context or default ClassLoader. True means use context ClassLoader.

Parameters: useContext True means use context ClassLoader

setUserClassNames

public void setUserClassNames(String userClassNames)
Sets the list of comma-delimited classes that represent individual users. The classes in the list must implement java.security.Principal. The supplied list of classes will be parsed when start is called.

start

public void start()
Prepare for active use of the public methods of this Component.

Throws: LifecycleException if this component detects a fatal error that prevents it from being started

stop

public void stop()
Gracefully shut down active use of the public methods of this Component.

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

Copyright © 2000-2011 Apache Software Foundation. All Rights Reserved.