glenn       2002/12/08 05:40:15

  Modified:    webapps/docs realm-howto.xml
               webapps/docs/config realm.xml
  Added:       catalina/src/share/org/apache/catalina/realm
                        DataSourceRealm.java
  Log:
  Port new DataSource Realm in Tomcat 4 to Catalina 2.0
  
  Revision  Changes    Path
  1.1                  
jakarta-tomcat-catalina/catalina/src/share/org/apache/catalina/realm/DataSourceRealm.java
  
  Index: DataSourceRealm.java
  ===================================================================
  /*
  * $Header: 
/home/cvs/jakarta-tomcat-catalina/catalina/src/share/org/apache/catalina/realm/DataSourceRealm.java,v
 1.1 2002/12/08 13:40:14 glenn Exp $
  * $Revision: 1.1 $
  * $Date: 2002/12/08 13:40:14 $
  *
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
  * Copyright (c) 1999 The Apache Software Foundation.  All rights
  * reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  *
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  *
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in
  *    the documentation and/or other materials provided with the
  *    distribution.
  *
  * 3. The end-user documentation included with the redistribution, if
  *    any, must include the following acknowlegement:
  *       "This product includes software developed by the
  *        Apache Software Foundation (http://www.apache.org/)."
  *    Alternately, this acknowlegement may appear in the software itself,
  *    if and wherever such third-party acknowlegements normally appear.
  *
  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
  *    Foundation" must not be used to endorse or promote products derived
  *    from this software without prior written permission. For written
  *    permission, please contact [EMAIL PROTECTED]
  *
  * 5. Products derived from this software may not be called "Apache"
  *    nor may "Apache" appear in their names without prior written
  *    permission of the Apache Group.
  *
  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  * SUCH DAMAGE.
  * ====================================================================
  *
  * This software consists of voluntary contributions made by many
  * individuals on behalf of the Apache Software Foundation.  For more
  * information on the Apache Software Foundation, please see
  * <http://www.apache.org/>.
  *
  * [Additional notices, if required by prior licensing conditions]
  *
  */
  
  
  package org.apache.catalina.realm;
  
  
  import java.io.File;
  import java.security.MessageDigest;
  import java.security.Principal;
  import java.sql.Connection;
  import java.sql.Driver;
  import java.sql.PreparedStatement;
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.util.ArrayList;
  import java.util.Properties;
  
  import javax.naming.InitialContext;
  import javax.naming.Context;
  import javax.naming.NamingException;
  import javax.sql.DataSource;
  
  import org.apache.catalina.Container;
  import org.apache.catalina.Lifecycle;
  import org.apache.catalina.LifecycleEvent;
  import org.apache.catalina.LifecycleException;
  import org.apache.catalina.LifecycleListener;
  import org.apache.catalina.Logger;
  import org.apache.catalina.Realm;
  import org.apache.catalina.Server;
  import org.apache.catalina.ServerFactory;
  import org.apache.catalina.core.StandardServer;
  import org.apache.catalina.util.HexUtils;
  import org.apache.catalina.util.LifecycleSupport;
  import org.apache.catalina.util.StringManager;
  import org.apache.catalina.util.Base64;
  
  /**
  *
  * Implmentation of <b>Realm</b> that works with any JDBC JNDI DataSource.
  * See the JDBCRealm.howto for more details on how to set up the database and
  * for configuration options.
  *
  * @author Glenn L. Nielsen
  * @author Craig R. McClanahan
  * @author Carson McDonald
  * @author Ignacio Ortega
  * @version $Revision: 1.1 $
  */
  
  public class DataSourceRealm
      extends RealmBase {
  
  
      // ----------------------------------------------------- Instance Variables
  
  
      /**
       * The generated string for the roles PreparedStatement
       */
      private StringBuffer preparedRoles = null;
  
  
      /**
       * The generated string for the credentials PreparedStatement
       */
      private StringBuffer preparedCredentials = null;
  
  
      /**
       * The name of the JNDI JDBC DataSource
       */
      protected String dataSourceName = null;
  
  
      /**
       * Descriptive information about this Realm implementation.
       */
      protected static final String info =
          "org.apache.catalina.realm.DataSourceRealm/1.0";
  
  
      /**
       * Descriptive information about this Realm implementation.
       */
      protected static final String name = "DataSourceRealm";
  
  
      /**
       * The column in the user role table that names a role
       */
      protected String roleNameCol = null;
  
  
      /**
       * The string manager for this package.
       */
      protected static final StringManager sm =
          StringManager.getManager(Constants.Package);
  
  
      /**
       * The column in the user table that holds the user's credintials
       */
      protected String userCredCol = null;
  
  
      /**
       * The column in the user table that holds the user's name
       */
      protected String userNameCol = null;
  
  
      /**
       * The table that holds the relation between user's and roles
       */
      protected String userRoleTable = null;
  
  
      /**
       * The table that holds user data.
       */
      protected String userTable = null;
  
  
      // ------------------------------------------------------------- Properties
  
  
      /**
       * Return the name of the JNDI JDBC DataSource.
       *
       */
      public String getDataSourceName() {
          return dataSourceName;
      }
  
      /**
       * Set the name of the JNDI JDBC DataSource.
       *
       * @param dataSourceName the name of the JNDI JDBC DataSource
       */
      public void setDataSourceName( String dataSourceName) {
        this.dataSourceName = dataSourceName;
      }
  
      /**
       * Return the column in the user role table that names a role.
       *
       */
      public String getRoleNameCol() {
          return roleNameCol;
      }
  
      /**
       * Set the column in the user role table that names a role.
       *
       * @param roleNameCol The column name
       */
      public void setRoleNameCol( String roleNameCol ) {
          this.roleNameCol = roleNameCol;
      }
  
      /**
       * Return the column in the user table that holds the user's credentials.
       *
       */
      public String getUserCredCol() {
          return userCredCol;
      }
  
      /**
       * Set the column in the user table that holds the user's credentials.
       *
       * @param userCredCol The column name
       */
      public void setUserCredCol( String userCredCol ) {
         this.userCredCol = userCredCol;
      }
  
      /**
       * Return the column in the user table that holds the user's name.
       *
       */
      public String getUserNameCol() {
          return userNameCol;
      }
  
      /**
       * Set the column in the user table that holds the user's name.
       *
       * @param userNameCol The column name
       */
      public void setUserNameCol( String userNameCol ) {
         this.userNameCol = userNameCol;
      }
  
      /**
       * Return the table that holds the relation between user's and roles.
       *
       */
      public String getUserRoleTable() {
          return userRoleTable;
      }
  
      /**
       * Set the table that holds the relation between user's and roles.
       *
       * @param userRoleTable The table name
       */
      public void setUserRoleTable( String userRoleTable ) {
          this.userRoleTable = userRoleTable;
      }
  
      /**
       * Return the table that holds user data..
       *
       */
      public String getUserTable() {
          return userTable;
      }
  
      /**
       * Set the table that holds user data.
       *
       * @param userTable The table name
       */
      public void setUserTable( String userTable ) {
        this.userTable = userTable;
      }
  
  
      // --------------------------------------------------------- Public Methods
  
  
      /**
       * Return the Principal associated with the specified username and
       * credentials, if there is one; otherwise return <code>null</code>.
       *
       * 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.
       *
       * @param username Username of the Principal to look up
       * @param credentials Password or other credentials to use in
       *  authenticating this username
       */
      public Principal authenticate(String username, String credentials) {
  
          Connection dbConnection = null;
  
          try {
  
              // Ensure that we have an open database connection
              dbConnection = open();
  
              // Acquire a Principal object for this user
              Principal principal = authenticate(dbConnection,
                                                 username, credentials);
  
              if( !dbConnection.getAutoCommit() ) {
                  dbConnection.commit();             
              }
  
              // Release the database connection we just used
              close(dbConnection);
              dbConnection = null;
  
              // Return the Principal (if any)
              return (principal);
  
          } catch (SQLException e) {
  
              // Log the problem for posterity
              log(sm.getString("dataSourceRealm.exception"), e);
  
              // Close the connection so that it gets reopened next time
              if (dbConnection != null)
                  close(dbConnection);
  
              // Return "not authenticated" for this request
              return (null);
  
          }
  
      }
  
  
      // -------------------------------------------------------- Package Methods
  
  
      // ------------------------------------------------------ Protected Methods
  
  
      /**
       * Return the Principal associated with the specified username and
       * credentials, if there is one; otherwise return <code>null</code>.
       *
       * @param dbConnection The database connection to be used
       * @param username Username of the Principal to look up
       * @param credentials Password or other credentials to use in
       *  authenticating this username
       *
       * @exception SQLException if a database error occurs
       */
      private Principal authenticate(Connection dbConnection,
                                                 String username,
                                                 String credentials)
          throws SQLException {
  
          ResultSet rs = null;
          PreparedStatement stmt = null;
          ArrayList list = null;
  
          try {
              // Look up the user's credentials
              String dbCredentials = null;
              stmt = credentials(dbConnection, username);
              rs = stmt.executeQuery();
              while (rs.next()) {
                  dbCredentials = rs.getString(1).trim();
              }
              rs.close();
              rs = null;
              stmt.close();
              stmt = null;
              if (dbCredentials == null) {
                  return (null);
              }
      
              // Validate the user's credentials
              boolean validated = false;
              if (hasMessageDigest()) {
                  // Hex hashes should be compared case-insensitive
                  validated = (digest(credentials).equalsIgnoreCase(dbCredentials));
              } else
                  validated = (digest(credentials).equals(dbCredentials));
      
              if (validated) {
                  if (debug >= 2)
                      log(sm.getString("dataSourceRealm.authenticateSuccess",
                                       username));
              } else {
                  if (debug >= 2)
                      log(sm.getString("dataSourceRealm.authenticateFailure",
                                       username));
                  return (null);
              }
      
              // Accumulate the user's roles
              list = new ArrayList();
              stmt = roles(dbConnection, username);
              rs = stmt.executeQuery();
              while (rs.next()) {
                  list.add(rs.getString(1).trim());
              }
          } finally {
              if (rs != null) {
                  rs.close();
              }
              if (stmt != null) {
                  stmt.close();
              }
          }
  
          // Create and return a suitable Principal for this user
          return (new GenericPrincipal(this, username, credentials, list));
  
      }
  
  
      /**
       * Close the specified database connection.
       *
       * @param dbConnection The connection to be closed
       */
      private void close(Connection dbConnection) {
  
          // Do nothing if the database connection is already closed
          if (dbConnection == null)
              return;
  
          // Close this database connection, and log any errors
          try {
              dbConnection.close();
          } catch (SQLException e) {
              log(sm.getString("dataSourceRealm.close"), e); // Just log it here
          }
  
      }
  
  
      /**
       * Open the specified database connection.
       *
       * @return Connection to the database
       */
      private Connection open() {
  
          try {
              StandardServer server = (StandardServer) ServerFactory.getServer();
              Context context = server.getGlobalNamingContext();
              DataSource dataSource = (DataSource)context.lookup(dataSourceName);
              return dataSource.getConnection();
          } catch (Exception e) {
              // Log the problem for posterity
              log(sm.getString("dataSourceRealm.exception"), e);
          }  
          return null;
      }
  
  
      /**
       * Return a PreparedStatement configured to perform the SELECT required
       * to retrieve user credentials for the specified username.
       *
       * @param dbConnection The database connection to be used
       * @param username Username for which credentials should be retrieved
       *
       * @exception SQLException if a database error occurs
       */
      private PreparedStatement credentials(Connection dbConnection,
                                              String username)
          throws SQLException {
  
          PreparedStatement credentials =
              dbConnection.prepareStatement(preparedCredentials.toString());
  
          credentials.setString(1, username);
          return (credentials);
  
      }
  
  
      /**
       * Return a short name for this Realm implementation.
       */
      protected String getName() {
  
          return (this.name);
  
      }
  
  
      /**
       * Return the password associated with the given principal's user name.
       */
      protected String getPassword(String username) {
  
          return (null);
  
      }
  
  
      /**
       * Return the Principal associated with the given user name.
       */
      protected Principal getPrincipal(String username) {
  
          return (null);
  
      }
  
  
  
      /**
       * Return a PreparedStatement configured to perform the SELECT required
       * to retrieve user roles for the specified username.
       *
       * @param dbConnection The database connection to be used
       * @param username Username for which roles should be retrieved
       *
       * @exception SQLException if a database error occurs
       */
      private PreparedStatement roles(Connection dbConnection, String username)
          throws SQLException {
  
          PreparedStatement roles = 
              dbConnection.prepareStatement(preparedRoles.toString());
  
          roles.setString(1, username);
          return (roles);
  
      }
  
  
      // ------------------------------------------------------ Lifecycle Methods
  
  
      /**
       *
       * Prepare for active use of the public methods of this Component.
       *
       * @exception LifecycleException if this component detects a fatal error
       *  that prevents it from being started
       */
      public void start() throws LifecycleException {
  
          // Create the roles PreparedStatement string
          preparedRoles = new StringBuffer("SELECT ");
          preparedRoles.append(roleNameCol);
          preparedRoles.append(" FROM ");
          preparedRoles.append(userRoleTable);
          preparedRoles.append(" WHERE ");
          preparedRoles.append(userNameCol);
          preparedRoles.append(" = ?");
  
          // Create the credentials PreparedStatement string
          preparedCredentials = new StringBuffer("SELECT ");
          preparedCredentials.append(userCredCol);
          preparedCredentials.append(" FROM ");
          preparedCredentials.append(userTable);
          preparedCredentials.append(" WHERE ");
          preparedCredentials.append(userNameCol);
          preparedCredentials.append(" = ?");
  
          // Validate that we can open our connection
          Connection conn = null;
          PreparedStatement roles = null;
          PreparedStatement credentials = null;
          try {
              conn = open();
              if (conn != null) {
                  roles = roles(conn,"");
                  credentials = credentials(conn,"");
                  if( !conn.getAutoCommit() ) {
                      conn.commit();             
                  }
              }
          } catch (SQLException e) {
              throw new LifecycleException(sm.getString("dataSourceRealm.open"), e);
          } finally {
              try {
                  if (conn != null) {
                     conn.close(); 
                  }
              } catch (SQLException e) {
                  throw new LifecycleException(sm.getString("dataSourceRealm.open"), 
e);
              }
          }
  
          // Perform normal superclass initialization
          super.start();
  
      }
  
  
      /**
       * Gracefully shut down active use of the public methods of this Component.
       *
       * @exception LifecycleException if this component detects a fatal error
       *  that needs to be reported
       */
      public void stop() throws LifecycleException {
  
          // Perform normal superclass finalization
          super.stop();
  
      }
  
  
  }
  
  
  
  1.3       +187 -0    jakarta-tomcat-catalina/webapps/docs/realm-howto.xml
  
  Index: realm-howto.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/realm-howto.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- realm-howto.xml   30 Jul 2002 03:58:28 -0000      1.2
  +++ realm-howto.xml   8 Dec 2002 13:40:14 -0000       1.3
  @@ -314,6 +314,193 @@
   </subsection>
   
   
  +<subsection name="DataSourceRealm">
  +
  +<h3>Introduction</h3>
  +
  +<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 4
  +<code>Realm</code> interface that looks up users in a relational database
  +accessed via a JNDI named JDBC DataSource.  There is substantial configuration
  +flexibility that lets you adapt to existing table and column names, as long
  +as your database structure conforms to the following requirements:</p>
  +<ul>
  +<li>There must be a table, referenced below as the <em>users</em> table,
  +    that contains one row for every valid user that this <code>Realm</code>
  +    should recognize.</li>
  +<li>The <em>users</em> table must contain at least two columns (it may
  +    contain more if your existing applications required it):
  +    <ul>
  +    <li>Username to be recognized by Tomcat when the user logs in.</li>
  +    <li>Password to be recognized by Tomcat when the user logs in.
  +        This value may in cleartext or digested - see below for more
  +        information.</li>
  +    </ul></li>    
  +<li>There must be a table, referenced below as the <em>user roles</em> table,
  +    that contains one row for every valid role that is assigned to a
  +    particular user.  It is legal for a user to have zero, one, or more than
  +    one valid role.</li>
  +<li>The <em>user roles</em> table must contain at least two columns (it may
  +    contain more if your existing applications required it):
  +    <ul>
  +    <li>Username to be recognized by Tomcat (same value as is specified
  +        in the <em>users</em> table).</li>
  +    <li>Role name of a valid role associated with this user.</li>
  +    </ul></li>    
  +</ul>
  +
  +<h3>Quick Start</h3>
  +                  
  +<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
  +<ol>              
  +<li>If you have not yet done so, create tables and columns in your database
  +    that conform to the requirements described above.</li>
  +<li>Configure a database username and password for use by Tomcat, that has
  +    at least read only access to the tables described above.  (Tomcat will
  +    never attempt to write to these tables.)</li>
  +<li>Configure a JNDI named JDBC DataSource for your database.  Refer to the
  +    <a href="jndi-datasource-examples-howto.xml">JNDI DataSource Example HOW-TO</a>
  +    for information on how to configure a JNDI named JDBC DataSource.</li>
  +<li>Set up a <code>&lt;Realm&gt;</code> element, as described below, in your
  +    <code>$CATALINA_HOME/conf/server.xml</code> file.</li>
  +<li>Restart Tomcat 4 if it is already running.</li>
  +</ol>
  +
  +<h3>Realm Element Attributes</h3>
  +
  +<p>To configure JDBCRealm, you will create a <code>&lt;Realm&gt;</code>
  +element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file,
  +as described <a href="#Configuring a Realm">above</a>.  The following
  +attributes are supported by this implementation:</p>
  +
  +<attributes>
  +
  +  <attribute name="className" required="true">
  +    <p>The fully qualified Java class name of this Realm implementation.
  +    You <strong>MUST</strong> specify the value
  +    "<code>org.apache.catalina.realm.JDBCRealm</code>" here.</p>
  +  </attribute>
  +
  +  <attribute name="connectionName" required="true">
  +    <p>The database username used to establish a JDBC connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionPassword" required="true">
  +    <p>The database password used to establish a JDBC connection.</p>
  +  </attribute>
  +
  +  <attribute name="connectionURL" required="true">
  +    <p>The database URL used to establish a JDBC connection.</p>
  +  </attribute>
  +    
  +  <attribute name="debug" required="false">
  +    <p>The level of debugging detail logged by this Realm
  +    to the associated <a href="config/logger.html">Logger</a>.  Higher numbers
  +    generate more detailed output.  If not specified, the default
  +    debugging detail level is zero (0).</p>
  +  </attribute>
  +    
  +  <attribute name="digest" required="false">
  +    <p>The digest algorithm used to store passwords in non-plaintext formats.
  +    Valid values are those accepted for the algorithm name by the
  +    <code>java.security.MessageDigest</code> class.  See
  +    <a href="#Digested Passwords">Digested Passwords</a> for more
  +    information.  If not specified, passwords are stored in clear text.</p>
  +  </attribute>
  +    
  +  <attribute name="driverName" required="true">
  +    <p>The fully qualified Java class name of the JDBC driver to be used.
  +    Consult the documentation for your JDBC driver for the appropriate
  +    value.</p>
  +  </attribute>
  +    
  +  <attribute name="roleNameCol" required="true">
  +    <p>The name of the column, in the <em>user roles</em> table, that
  +    contains the name of a role assigned to this user.</p>
  +  </attribute>
  +    
  +  <attribute name="userCredCol" required="true">
  +    <p>The name of the column, in the <em>users</em> table, that contains
  +    the password for this user (either in clear text, or digested if the
  +    <code>digest</code> attribute is set).</p>
  +  </attribute>
  +    
  +  <attribute name="userNameCol" required="true">
  +    <p>The name of the column, in the <em>users</em> and <em>user roles</em>
  +    tables, that contains the username of this user.</p>
  +  </attribute>
  +
  +  <attribute name="userRoleTable" required="true">
  +    <p>The name of the table that contains one row for each <em>role</em>
  +    assigned to a particular <em>username</em>.  This table must include at
  +    least the columns named by the <code>userNameCol</code> and
  +    <code>roleNameCol</code> attributes.</p>
  +  </attribute>
  +
  +  <attribute name="userTable" required="true">
  +    <p>The name of the table that contains one row for each <em>username</em>
  +    to be recognized by Tomcat.  This table must include at least the columns
  +    named by the <code>userNameCol</code> and <code>userCredCol</code>
  +    attributes.</p>
  +  </attribute>
  +
  +</attributes>
  +
  +<h3>Example</h3>
  +
  +<p>An example SQL script to create the needed tables might look something
  +like this (adapt the syntax as required for your particular database):</p>
  +<source>
  +create table users (
  +  user_name         varchar(15) not null primary key,
  +  user_pass         varchar(15) not null
  +);
  +
  +create table user_roles (
  +  user_name         varchar(15) not null,
  +  role_name         varchar(15) not null,
  +  primary key (user_name, role_name)
  +);
  +</source>
  +
  +<p>Here is an example for using a MySQL database called "authority", configured
  +with the tables described above, and accessed with the JNDI JDBC DataSource with
  +name "java:/comp/env/jdbc/authority".</p>
  +<source>
  +&lt;Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99"
  +   dataSourceName="java:/comp/env/jdbc/authority"
  +   userTable="users" userNameCol="user_name" userCredCol="user_pass"
  +   userRoleTable="user_roles" roleNameCol="role_name"/&gt;
  +</source>
  +
  +<h3>Additional Notes</h3>
  +
  +<p>DataSourceRealm operates according to the following rules:</p>
  +<ul>
  +<li>When a user attempts to access a protected resource for the first time,
  +    Tomcat 4 will call the <code>authenticate()</code> method of this
  +    <code>Realm</code>.  Thus, any changes you have made to the database
  +    directly (new users, changed passwords or roles, etc.) will be immediately
  +    reflected.</li>
  +<li>Once a user has been authenticated, the user (and his or her associated
  +    roles) are cached within Tomcat for the duration of the user's login.
  +    (For FORM-based authentication, that means until the session times out or
  +    is invalidated; for BASIC authentication, that means until the user
  +    closes their browser).  Any changes to the database information for an
  +    already authenticated user will <strong>not</strong> be reflected until
  +    the next time that user logs on again.</li>
  +<li>Administering the information in the <em>users</em> and <em>user roles</em>
  +    table is the responsibility of your own applications.  Tomcat does not
  +    provide any built-in capabilities to maintain users and roles.</li>
  +<li>Debugging and exception messages logged by this <code>Realm</code> will
  +    be recorded by the <code>Logger</code> that is associated with our
  +    surrounding <code>Context</code>, <code>Host</code>, or
  +    <code>Engine</code>.  By default, the corresponding Logger will create a
  +    log file in the <code>$CATALINA_HOME/logs</code> directory.</li>
  +</ul>
  +
  +</subsection>
  +
  +
   <subsection name="JNDIRealm">
   
   <h3>Introduction</h3>
  
  
  
  1.4       +74 -0     jakarta-tomcat-catalina/webapps/docs/config/realm.xml
  
  Index: realm.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/config/realm.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- realm.xml 12 Nov 2002 20:22:07 -0000      1.3
  +++ realm.xml 8 Dec 2002 13:40:14 -0000       1.4
  @@ -155,6 +155,80 @@
       JDBC Database Realm component.</p>
   
   
  +    <h3>
  +      DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm)
  +    </h3>
  +
  +    <p>The <strong>DataSource Database Realm</strong> connects Catalina to
  +    a relational database, accessed through a JNDI named JDBC DataSource
  +    to perform lookups of usernames, passwords, and their associated
  +    roles.  Because the lookup is done each time that it is required,
  +    changes to the database will be immediately reflected in the
  +    information used to authenticate new logins.</p>
  +
  +    <p>The JDBC Realm uses a single db connection. This requires that
  +    realm based authentication be synchronized, i.e. only one authentication
  +    can be done at a time. This could be a bottleneck for applications
  +    with high volumes of realm based authentications.</p>
  +
  +    <p>The DataSource Database Realm supports simultaneous realm based
  +    authentications and allows the underlying JDBC DataSource to
  +    handle optimizations like database connection pooling.</p>
  +
  +    <p>A rich set of additional attributes lets you configure the name
  +    of the JNDI JDBC DataSource, as well as the table and
  +    column names used to retrieve the required information:</p>
  +
  +    <attributes>
  +
  +      <attribute name="dataSourceName" required="true">
  +        <p>The name of the JNDI JDBC DataSource for this Realm.</p>
  +      </attribute>
  +
  +      <attribute name="digest" required="false">
  +        <p>The name of the <code>MessageDigest</code> algorithm used
  +        to encode user passwords stored in the database.  If not specified,
  +        user passwords are assumed to be stored in clear-text.</p>
  +      </attribute>
  +
  +      <attribute name="roleNameCol" required="true">
  +        <p>Name of the column, in the "user roles" table, which contains
  +        a role name assigned to the corresponding user.</p>
  +      </attribute>
  +
  +      <attribute name="userCredCol" required="true">
  +        <p>Name of the column, in the "users" table, which contains
  +        the user's credentials (i.e. password(.  If a value for the
  +        <code>digest</code> attribute is specified, this component
  +        will assume that the passwords have been encoded with the
  +        specified algorithm.  Otherwise, they will be assumed to be
  +        in clear text.</p>
  +      </attribute>
  +
  +      <attribute name="userNameCol" required="true">
  +        <p>Name of the column, in the "users" and "user roles" table,
  +        that contains the user's username.</p>
  +      </attribute>
  +
  +      <attribute name="userRoleTable" required="true">
  +        <p>Name of the "user roles" table, which must contain columns
  +        named by the <code>userNameCol</code> and <code>roleNameCol</code>
  +        attributes.</p>
  +      </attribute>
  +
  +      <attribute name="userTable" required="true">
  +        <p>Name of the "users" table, which must contain columns named
  +        by the <code>userNameCol</code> and <code>userCredCol</code>
  +        attributes.</p>
  +      </attribute>
  +
  +    </attributes>
  +
  +    <p>See the <a href="../realm-howto.html#DataSourceRealm">
  +    DataSource Realm HOW-TO</a> for more information on setting up container
  +    managed security using the DataSource Database Realm component.</p>
  +
  +
       <h3>JNDI Directory Realm (org.apache.catalina.realm.JNDIRealm)</h3>
   
   
  
  
  

--
To unsubscribe, e-mail:   <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>

Reply via email to