OpenNMS API 1.2.9

org.opennms.web.authenticate
Class OpenNMSTomcatRealm

java.lang.Object
  extended byorg.apache.catalina.realm.RealmBase
      extended byorg.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.