## org.apache.catalina.realm
Class JAASRealm

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

All Implemented Interfaces:
  Lifecycle, javax.management.MBeanRegistration, 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.
- By default, the enclosing Container's name serves as the application name used to obtain the JAAS LoginContext ("Catalina" in a default installation). Tomcat must be able to find an application with this name in the JAAS configuration file. Here is a hypothetical JAAS configuration file entry for a database-oriented login module that uses a Tomcat-managed JNDI database resource:

  >     Catalina {
  >     org.foobar.auth.DatabaseLoginModule REQUIRED
  >         JNDI_RESOURCE=jdbc/AuthDB
  >       USER_TABLE=users
  >       USER_ID_COLUMN=id
  >       USER_NAME_COLUMN=name
  >       USER_CREDENTIAL_COLUMN=password
  >       ROLE_TABLE=roles
  >       ROLE_NAME_COLUMN=name
  >       PRINCIPAL_FACTORY=org.foobar.auth.impl.SimplePrincipalFactory;
  >     };

- To set the JAAS configuration file location, set the `CATALINA_OPTS` environment variable similar to the following:

  > `CATALINA_OPTS="-Djava.security.auth.login.config=$CATALINA_HOME/conf/jaas.config"`

- As part of the login process, JAASRealm registers its own `CallbackHandler`, called (unsurprisingly) `JAASCallbackHandler`. This handler supplies the HTTP requests's username and credentials to the user-supplied `LoginModule`
- As with other `Realm` implementations, digested passwords are supported if the `<Realm>` element in `server.xml` contains a `digest` attribute; `JAASCallbackHandler` will digest the password prior to passing it back to the `LoginModule`

Version:
  $Revision: 1.6.2.4 $ $Date: 2004/10/01 12:28:47 $
Author:
  Craig R. McClanahan, Yoav Shapira, Andrew R. Jaquith

Field Summary
`protected java.lang.String` `appName` The application name passed to the JAAS `LoginContext`, which uses it to select the set of relevant `LoginModule`s.
`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.List` `roleClasses` The list of role class names, split out for easy processing.
`protected java.lang.String` `roleClassNames` Comma-delimited list of `java.security.Principal` classes that represent security roles.
`protected java.util.Map` `roleMap` Map associating each user `Principal` object with an array of role `Principal`s.
`protected static StringManager` `sm` The string manager for this package.
`protected boolean` `useContextClassLoader` Whether to use context ClassLoader or default ClassLoader.
`protected java.util.List` `userClasses` The set of user class names, split out for easy processing.
`protected java.lang.String` `userClassNames` Comma-delimited list of `java.security.Principal` classes that represent individual users.

Fields inherited from class org.apache.catalina.realm.RealmBase
`container, controller, debug, digest, digestEncoding, domain, host, initialized, lifecycle, md, md5Encoder, md5Helper, mserver, oname, path, started, support, type, 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(java.lang.String username, javax.security.auth.Subject subject)` Identify 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()`
`boolean` `hasRole(java.security.Principal principal, java.lang.String role)` Returns `true` if the specified user `Principal` has the specified security role, within the context of this `Realm`; otherwise return `false`.
`boolean` `isUseContextClassLoader()` Returns whether to use the context or default ClassLoader.
`protected java.lang.String` `makeLegalForJAAS(java.lang.String src)` Ensure the given name is legal for JAAS configuration.
`void` `setAppName(java.lang.String name)` Deprecated. JAAS should use the `Engine` (domain) name and webpp/host overrides
`void` `setContainer(Container container)` Set the Container with which this Realm has been associated.
`void` `setRoleClassNames(java.lang.String roleClassNames)` Sets the list of comma-delimited classes that represent roles.
`void` `setUseContextClassLoader(boolean useContext)` Sets whether to use the context or default ClassLoader.
`void` `setUserClassNames(java.lang.String userClassNames)` Sets the list of comma-delimited classes that represent individual users.
`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, destroy, digest, Digest, findLifecycleListeners, findSecurityConstraints, getContainer, getController, getDebug, getDigest, getDigest, getDigestEncoding, getDomain, getInfo, getObjectName, getType, getValidate, hasMessageDigest, hasResourcePermission, hasUserDataPermission, init, log, log, main, postDeregister, postRegister, preDeregister, preRegister, removeLifecycleListener, removePropertyChangeListener, setController, setDebug, setDigest, setDigestEncoding, 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 `LoginModule`s.

### 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.List 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.List userClasses

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

### roleMap

    protected java.util.Map roleMap

  Map associating each user `Principal` object with an array of role `Principal`s. This Map is read when `hasRole` is called.

### useContextClassLoader

    protected boolean useContextClassLoader

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

### roleClassNames

    protected java.lang.String roleClassNames

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

### userClassNames

    protected java.lang.String userClassNames

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

Constructor Detail

### JAASRealm

    public JAASRealm()

Method Detail

### setAppName

    public void setAppName(java.lang.String name)

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

  setter for the `appName` member variable

### getAppName

    public java.lang.String getAppName()

  getter for the `appName` member variable

### 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

### 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

### setContainer

    public void setContainer(Container container)

  Description copied from class: `RealmBase`
  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

### getRoleClassNames

    public java.lang.String getRoleClassNames()

### setRoleClassNames

    public void setRoleClassNames(java.lang.String roleClassNames)

  Sets the list of comma-delimited classes that represent roles. The classes in the list must implement `java.security.Principal`. When this accessor is called (for example, by a `Digester` instance parsing the configuration file), it will parse the class names and store the resulting string(s) into the `ArrayList` field roleClasses.

### getUserClassNames

    public java.lang.String getUserClassNames()

### setUserClassNames

    public void setUserClassNames(java.lang.String userClassNames)

  Sets the list of comma-delimited classes that represent individual users. The classes in the list must implement `java.security.Principal`. When this accessor is called (for example, by a `Digester` instance parsing the configuration file), it will parse the class names and store the resulting string(s) into the `ArrayList` field userClasses.

### 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

### hasRole

    public boolean hasRole(java.security.Principal principal,
                           java.lang.String role)

  Returns `true` if the specified user `Principal` has the specified security role, within the context of this `Realm`; otherwise return `false`. This will be true when an associated role `Principal` can be found whose `getName` method returns a `String` equalling the specified role.

  Specified by:
    `hasRole` in interface `Realm`
  Overrides:
    `hasRole` in class `RealmBase`
  Parameters:
    `principal` - `Principal` for whom the role is to be checked
    `role` - Security role to be checked

### 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(java.lang.String username,
                                                      javax.security.auth.Subject subject)

  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 tha 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

### makeLegalForJAAS

    protected java.lang.String makeLegalForJAAS(java.lang.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

### 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-2003 Apache Software Foundation. All Rights Reserved.