OpenNMS API 1.2.9

## org.opennms.web.authenticate
Class OpenNMSTomcatRealm

    java.lang.Object
      org.apache.catalina.realm.RealmBase
          org.opennms.web.authenticate.OpenNMSTomcatRealm

All Implemented Interfaces:
  org.apache.catalina.Lifecycle, org.apache.catalina.Realm

public class OpenNMSTomcatRealm
extends org.apache.catalina.realm.RealmBase

Implements the interface to allow Tomcat to check our users.xml file to authenticate users.

This class is Tomcat-specific and will not be portable to other servlet containers. It relies on packages supplied with Tomcat.

Author:
  Lawrence Karnowski, Eric Molitor, OpenNMS

Field Summary
`protected java.lang.String` `HOME_DIR` The relative path to find the users.xml file
`protected java.lang.String` `info` Descriptive information about this Realm implementation.
`protected org.apache.log4j.Category` `log` The Log4J category for logging web authentication messages.
`protected java.util.Map` `magicRoleMapping` A mapping of special roles to authorized users.
`protected java.io.File` `magicUsersFile` The magic-users.properties file that is read for the list of special users, their passwords, and authorization roles.
`protected long` `magicUsersLastModified` The time (in milliseconds) that the magic-users.properties file was last modified.
`protected static java.lang.String` `name` Descriptive information about this Realm implementation.
`protected java.util.HashMap` `principals` The set of valid Principals for this Realm, keyed by user name.
`protected java.beans.PropertyChangeSupport` `propertyChangeSupport` Convenient support for PropertyChangeEvents.
`protected java.lang.String` `resourceName` The global JNDI name of the `UserDatabase` resource we will be utilizing.
`private static org.apache.catalina.util.StringManager` `sm` The string manager for this package.

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
`START_EVENT, STOP_EVENT`

Constructor Summary
`OpenNMSTomcatRealm()` Create a new instance.

Method Summary
`void` `addPropertyChangeListener(java.beans.PropertyChangeListener listener)` Add a property change listener to this component.
`java.security.Principal` `authenticate(java.lang.String username, byte[] credentials)` Return the Principal associated with the specified username and credentials, if there is one; otherwise return `null`.
`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`.
`java.security.Principal` `authenticate(java.lang.String username, java.lang.String digest, java.lang.String nonce, java.lang.String nc, java.lang.String cnonce, java.lang.String qop, java.lang.String realm, java.lang.String md5a2)` Not implemented.
`java.security.Principal` `authenticate(java.security.cert.X509Certificate[] certs)` Not implemented.
`org.apache.catalina.Container` `getContainer()` Return the Container with which this Realm has been associated.
`java.lang.String` `getInfo()` Return descriptive information about this Realm implementation and the corresponding version number, in the format `<description>/<version>`.
`protected java.lang.String` `getName()`
`protected java.lang.String` `getPassword(java.lang.String s)`
`protected java.security.Principal` `getPrincipal(java.lang.String userName)`
`java.lang.String` `getResourceName()` Return the global JNDI name of the `UserDatabase` resource we will be using.
`boolean` `hasRole(java.security.Principal principal, java.lang.String role)` Returns true for any specified user if the role is `Authentication.USER_ROLE`, and will additionally return true for the admin user if the role is `Authentication.ADMIN_ROLE`.
`protected boolean` `isParseNecessary()` Checks the last modified time of the user and magic users files against the last known last modified time.
`protected void` `parse()` Convenience method for parsing the users.xml file.
`protected java.util.Map[]` `parseMagicUsers()` Parses the magic-users.properties file into two mappings: from magic username to password, and from magic role to authorized users of that role.
`void` `removePropertyChangeListener(java.beans.PropertyChangeListener listener)` Remove a property change listener from this component.
`void` `setContainer(org.apache.catalina.Container container)` Set the Container with which this Realm has been associated.
`void` `setHomeDir(java.lang.String homeDir)` Called by tomcat to set the home directory where the app is running from and to handle the userFile attribute in the Realm tag in the server.xml file.
`void` `setResourceName(java.lang.String resourceName)` Set the global JNDI name of the `UserDatabase` resource we will be using.
`void` `setUserFile(java.lang.String filename)` Deprecated.
`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, digest, Digest, getDebug, getDigest, getDigest, getValidate, hasMessageDigest, log, log, main, removeLifecycleListener, setDebug, setDigest, setValidate`

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

Field Detail

### HOME_DIR

    protected java.lang.String HOME_DIR

  The relative path to find the users.xml file

### info

    protected 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

### resourceName

    protected java.lang.String resourceName

  The global JNDI name of the `UserDatabase` resource we will be utilizing.

### sm

    private static org.apache.catalina.util.StringManager sm

  The string manager for this package.

### principals

    protected java.util.HashMap principals

  The set of valid Principals for this Realm, keyed by user name.

### propertyChangeSupport

    protected java.beans.PropertyChangeSupport propertyChangeSupport

  Convenient support for PropertyChangeEvents.

### magicUsersFile

    protected java.io.File magicUsersFile

  The magic-users.properties file that is read for the list of special users, their passwords, and authorization roles.

### magicUsersLastModified

    protected long magicUsersLastModified

  The time (in milliseconds) that the magic-users.properties file was last modified. This value is kept so that the users.xml file will be reparsed anytime it is modified.

### log

    protected org.apache.log4j.Category log

  The Log4J category for logging web authentication messages.

### magicRoleMapping

    protected java.util.Map magicRoleMapping

  A mapping of special roles to authorized users. Each role name key contains a `List` value of authorized user names.

Constructor Detail

### OpenNMSTomcatRealm

    public OpenNMSTomcatRealm()

  Create a new instance.

Method Detail

### getResourceName

    public java.lang.String getResourceName()

  Return the global JNDI name of the `UserDatabase` resource we will be using.

### setResourceName

    public void setResourceName(java.lang.String resourceName)

  Set the global JNDI name of the `UserDatabase` resource we will be using.

  Parameters:
    `resourceName` - The new global JNDI name

### parse

    protected void parse()

  Convenience method for parsing the users.xml file.

  This method is synchronized so only one thread at a time can parse the users.xml file and create the `principal` instance variable.

### getContainer

    public org.apache.catalina.Container getContainer()

  Return the Container with which this Realm has been associated.

### setContainer

    public void setContainer(org.apache.catalina.Container container)

  Set the Container with which this Realm has been associated.

  Parameters:
    `container` - The associated Container

### getInfo

    public java.lang.String getInfo()

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

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

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

### authenticate

    public java.security.Principal authenticate(java.lang.String username,
                                                byte[] 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 java.security.Principal authenticate(java.lang.String username,
                                                java.lang.String digest,
                                                java.lang.String nonce,
                                                java.lang.String nc,
                                                java.lang.String cnonce,
                                                java.lang.String qop,
                                                java.lang.String realm,
                                                java.lang.String md5a2)

  Not implemented.

  Throws:
    `java.lang.IllegalStateException` - because this method is not implemented.

### authenticate

    public java.security.Principal authenticate(java.security.cert.X509Certificate[] certs)

  Not implemented.

  Throws:
    `java.lang.IllegalStateException` - because this method is not implemented.

### hasRole

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

  Returns true for any specified user if the role is `Authentication.USER_ROLE`, and will additionally return true for the admin user if the role is `Authentication.ADMIN_ROLE`. Otherwise this method returns false.

  Note that no logging takes place in this method because it is called very frequently. Logging messages here could greatly reduce page-serving performance and would quickly flood the server logs with not very useful information.

  Parameters:
    `principal` -
    `role` - role to be checked

### addPropertyChangeListener

    public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

  Add a property change listener to this component.

  Parameters:
    `listener` - The listener to add

### removePropertyChangeListener

    public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

  Remove a property change listener from this component.

  Parameters:
    `listener` - The listener to remove

### getName

    protected java.lang.String getName()

### getPassword

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

### getPrincipal

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

### setUserFile

    public void setUserFile(java.lang.String filename)

  Deprecated.

  Called by tomcat to handle the userFile attribute in the Realm tag in the server.xml file.

### setHomeDir

    public void setHomeDir(java.lang.String homeDir)

  Called by tomcat to set the home directory where the app is running from and to handle the userFile attribute in the Realm tag in the server.xml file.

### isParseNecessary

    protected boolean isParseNecessary()

  Checks the last modified time of the user and magic users files against the last known last modified time. If the times are different, then the files must be reparsed.

  Note that the `lastModified` variables are not set here. This is in case there is a problem parsing either file. If we set the value here, and then try to parse and fail, then we will not try to parse again until the file changes again. Instead, when we see the file changes, we continue parsing attempts until the parsing succeeds.

### parseMagicUsers

    protected java.util.Map[] parseMagicUsers()
                                       throws java.io.FileNotFoundException,
                                              java.io.IOException

  Parses the magic-users.properties file into two mappings: from magic username to password, and from magic role to authorized users of that role.

  Throws:
    `java.io.FileNotFoundException`
    `java.io.IOException`

### start

    public void start()
               throws org.apache.catalina.LifecycleException

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

  Throws:
    `org.apache.catalina.LifecycleException` - if this component detects a fatal error that prevents it from being started

### stop

    public void stop()
              throws org.apache.catalina.LifecycleException

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

  Throws:
    `org.apache.catalina.LifecycleException` - if this component detects a fatal error that needs to be reported

OpenNMS API 1.2.9

Generated by ranger on May 19 2007 2335.