## org.apache.catalina.realm
Class JAASRealm

    java.lang.Object
      org.apache.catalina.realm.RealmBase
          org.apache.catalina.realm.JAASRealm

All Implemented Interfaces:
  Lifecycle, Realm

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:

- The JAAS `LoginModule` is assumed to return a `Subject with at least one `Principal` instance representing the user himself or herself, and zero or more separate `Principals` representing the security roles authorized for this user.`
- On the `Principal` representing the user, the Principal name is an appropriate value to return via the Servlet API method `HttpServletRequest.getRemoteUser()`.
- On the `Principals` representing the security roles, the name is the name of the authorized security role.
- This Realm will be configured with two lists of fully qualified Java class names of classes that implement `java.security.Principal` - one that identifies class(es) representing a user, and one that identifies class(es) representing a security role.
- As this Realm iterates over the `Principals` returned by `Subject.getPrincipals()`, it will identify the first `Principal` that matches the "user classes" list as the `Principal` for this user.
- As this Realm iterates over the `Princpals` returned by `Subject.getPrincipals()`, it will accumulate the set of all `Principals` matching the "role classes" list as identifying the security roles for this user.
- It is a configuration error for the JAAS login method to return a validated `Subject` without a `Principal` that matches the "user classes" list.

Version:
  $Revision: 1.5 $ $Date: 2004/08/26 21:37:21 $
Author:
  Craig R. McClanahan

Field Summary
`protected java.lang.String` `appName` The application name passed to the JAAS `LoginContext`, which uses it to select the set of relevant `LoginModules`.
`protected static java.lang.String` `info` Descriptive information about this Realm implementation.
`protected static java.lang.String` `name` Descriptive information about this Realm implementation.
`protected java.util.ArrayList` `roleClasses` The list of role class names, split out for easy processing.
`protected java.lang.String` `roleClassNames` Comma-delimited list of `javax.security.Principal` classes that represent security roles.
`protected static StringManager` `sm` The string manager for this package.
`protected java.util.ArrayList` `userClasses` The set of user class names, split out for easy processing.
`protected java.lang.String` `userClassNames` Comma-delimited list of `javax.security.Principal` classes that represent individual users.

Fields inherited from class org.apache.catalina.realm.RealmBase
`container, debug, digest, lifecycle, md, md5Encoder, md5Helper, started, support, validate`

Fields inherited from interface org.apache.catalina.Lifecycle
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT`

Constructor Summary
`JAASRealm()`

Method Summary
`java.security.Principal` `authenticate(java.lang.String username, java.lang.String credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
`protected java.security.Principal` `createPrincipal(javax.security.auth.Subject subject)` Construct and return a `java.security.Principal` instance representing the authenticated user for the specified Subject.
`java.lang.String` `getAppName()` getter for the appName member variable
`protected java.lang.String` `getName()` Return a short name for this Realm implementation.
`protected java.lang.String` `getPassword(java.lang.String username)` Return the password associated with the given principal's user name.
`protected java.security.Principal` `getPrincipal(java.lang.String username)` Return the Principal associated with the given user name.
`java.lang.String` `getRoleClassNames()`
`java.lang.String` `getUserClassNames()`
`void` `setAppName(java.lang.String name)` setter for the appName member variable
`void` `setRoleClassNames(java.lang.String roleClassNames)`
`void` `setUserClassNames(java.lang.String userClassNames)`
`void` `start()` Prepare for active use of the public methods of this Component.
`void` `stop()` Gracefully shut down active use of the public methods of this Component.

Methods inherited from class org.apache.catalina.realm.RealmBase
`addLifecycleListener, addPropertyChangeListener, authenticate, authenticate, authenticate, digest, Digest, findLifecycleListeners, getContainer, getDebug, getDigest, getDigest, getInfo, getValidate, hasMessageDigest, hasRole, log, log, main, removeLifecycleListener, removePropertyChangeListener, setContainer, setDebug, setDigest, setValidate`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### appName

    protected java.lang.String appName

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

### info

    protected static final java.lang.String info

  Descriptive information about this Realm implementation.

  See Also:
    Constant Field Values

### name

    protected static final java.lang.String name

  Descriptive information about this Realm implementation.

  See Also:
    Constant Field Values

### roleClasses

    protected java.util.ArrayList roleClasses

  The list of role class names, split out for easy processing.

### sm

    protected static final StringManager sm

  The string manager for this package.

### userClasses

    protected java.util.ArrayList userClasses

  The set of user class names, split out for easy processing.

### roleClassNames

    protected java.lang.String roleClassNames

  Comma-delimited list of `javax.security.Principal` classes that represent security roles.

### userClassNames

    protected java.lang.String userClassNames

  Comma-delimited list of `javax.security.Principal` classes that represent individual users.

Constructor Detail

### JAASRealm

    public JAASRealm()

Method Detail

### setAppName

    public void setAppName(java.lang.String name)

  setter for the appName member variable

### getAppName

    public java.lang.String getAppName()

  getter for the appName member variable

### getRoleClassNames

    public java.lang.String getRoleClassNames()

### setRoleClassNames

    public void setRoleClassNames(java.lang.String roleClassNames)

### getUserClassNames

    public java.lang.String getUserClassNames()

### setUserClassNames

    public void setUserClassNames(java.lang.String userClassNames)

### authenticate

    public java.security.Principal authenticate(java.lang.String username,
                                                java.lang.String credentials)

  Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`. If there are any errors with the JDBC connection, executing the query or anything we return null (don't authenticate). This event is also logged, and the connection will be closed so that a subsequent request will automatically re-open it.

  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

### getName

    protected java.lang.String getName()

  Return a short name for this Realm implementation.

  Specified by:
    `getName` in class `RealmBase`

### getPassword

    protected java.lang.String getPassword(java.lang.String username)

  Return the password associated with the given principal's user name.

  Specified by:
    `getPassword` in class `RealmBase`

### getPrincipal

    protected java.security.Principal getPrincipal(java.lang.String username)

  Return the Principal associated with the given user name.

  Specified by:
    `getPrincipal` in class `RealmBase`

### createPrincipal

    protected java.security.Principal createPrincipal(javax.security.auth.Subject subject)

  Construct and return a `java.security.Principal` instance representing the authenticated user for the specified Subject. If no such Principal can be constructed, return `null`.

  Parameters:
    `subject` - The Subject representing the logged in user

### start

    public void start()
               throws LifecycleException

  Prepare for active use of the public methods of this Component.

  Specified by:
    `start` in interface `Lifecycle`
  Overrides:
    `start` in class `RealmBase`
  Throws:
    `LifecycleException` - if this component detects a fatal error that prevents it from being started

### stop

    public void stop()
              throws LifecycleException

  Gracefully shut down active use of the public methods of this Component.

  Specified by:
    `stop` in interface `Lifecycle`
  Overrides:
    `stop` in class `RealmBase`
  Throws:
    `LifecycleException` - if this component detects a fatal error that needs to be reported

Copyright ? 2000-2002 Apache Software Foundation. All Rights Reserved.