From c69228c70151d0bd56bb82365132c3cf11c89aa3 Mon Sep 17 00:00:00 2001 From: markt Date: Mon, 7 Sep 2009 13:01:59 +0000 Subject: [PATCH] Remove attribute duplication - pages were often out of sync git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@812119 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/realm-howto.xml | 456 ++----------------------------------------- 1 file changed, 21 insertions(+), 435 deletions(-) diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml index 0e3cba334..7b5b8b479 100644 --- a/webapps/docs/realm-howto.xml +++ b/webapps/docs/realm-howto.xml @@ -352,74 +352,9 @@ database structure conforms to the following requirements:

To configure JDBCRealm, you will create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml file, -as described above. The following -attributes are supported by this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.JDBCRealm" here.

- - - -

The database username used to establish a JDBC connection.

- - - -

The database password used to establish a JDBC connection.

- - - -

The database URL used to establish a JDBC connection.

- - - -

The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - java.security.MessageDigest class. See - Digested Passwords for more - information. If not specified, passwords are stored in clear text.

- - - -

The fully qualified Java class name of the JDBC driver to be used. - Consult the documentation for your JDBC driver for the appropriate - value.

- - - -

The name of the column, in the user roles table, that - contains the name of a role assigned to this user.

- - - -

The name of the column, in the users table, that contains - the password for this user (either in clear text, or digested if the - digest attribute is set).

- - - -

The name of the column, in the users and user roles - tables, that contains the username of this user.

- - - -

The name of the table that contains one row for each role - assigned to a particular username. This table must include at - least the columns named by the userNameCol and - roleNameCol attributes.

- - - -

The name of the table that contains one row for each username - to be recognized by Tomcat. This table must include at least the columns - named by the userNameCol and userCredCol - attributes.

- - - +as described above. The attributes for the +JDBCRealm are defined in the Realm configuration +documentation.

Example

@@ -530,70 +465,9 @@ as your database structure conforms to the following requirements:

To configure DataSourceRealm, you will create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml file, -as described above. The following -attributes are supported by this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.DataSourceRealm" here.

- - - -

The JNDI named JDBC DataSource for your database. If the DataSource is - local to the context, the name is relative to java:/comp/env, - and otherwise the name should match the name used to define the global - DataSource.

- - - -

The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - java.security.MessageDigest class. See - Digested Passwords for more - information. If not specified, passwords are stored in clear text.

- - - -

When the realm is nested inside a Context element, this allows the - realm to use a DataSource defined for the Context rather than a global - DataSource. If not specified, the default is false: use a - global DataSource.

- - - -

The name of the column, in the user roles table, that - contains the name of a role assigned to this user.

- - - -

The name of the column, in the users table, that contains - the password for this user (either in clear text, or digested if the - digest attribute is set).

- - - -

The name of the column, in the users and user roles - tables, that contains the username of this user.

- - - -

The name of the table that contains one row for each role - assigned to a particular username. This table must include at - least the columns named by the userNameCol and - roleNameCol attributes.

- - - -

The name of the table that contains one row for each username - to be recognized by Tomcat. This table must include at least the columns - named by the userNameCol and userCredCol - attributes.

- - - +as described above. The attributes for the +DataSourceRealm are defined in the Realm +configuration documentation.

Example

@@ -839,199 +713,9 @@ the name of this attribute.

To configure JNDIRealm, you will create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml file, -as described above. The following -attributes are supported by this implementation:

- - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.JNDIRealm" here.

- - - -

Microsoft Active Directory often returns referrals. - When iterating over NamingEnumerations these lead to - PartialResultExceptions. If you want us to ignore those exceptions, - set this attribute to "true". Unfortunately there's no stable way - to detect, if the Exceptions really come from an AD referral. - The default value is "false".

- - - -

If a socket connection can not be made to the provider at - the connectionURL an attempt will be made to use the - alternateURL.

- - - -

A string specifying the type of authentication to use. - "none", "simple", "strong" or a provider specific definition - can be used. If no value is given the providers default is used.

- - - -

A role name assigned to each successfully authenticated user in - addition to the roles retrieved from LDAP. If not specified, only - the roles retrieved via LDAP are used.

- - - -

The directory username to use when establishing a - connection to the directory for LDAP search operations. If not - specified an anonymous connection is made, which is often - sufficient unless you specify the userPassword - property.

- - - -

The directory password to use when establishing a - connection to the directory for LDAP search operations. If not - specified an anonymous connection is made, which is often - sufficient unless you specify the userPassword - property.

- - - -

The connection URL to be passed to the JNDI driver when - establishing a connection to the directory.

- - - -

The fully qualified Java class name of the JNDI context - factory to be used for this connection. By default, the standard - JNDI LDAP provider is used - (com.sun.jndi.ldap.LdapCtxFactory).

- - - -

The digest algorithm to apply to the plaintext password offered - by the user before comparing it with the value retrieved from the - directory. Valid values are those accepted for the algorithm name - by the java.security.MessageDigest class. See Digested Passwords for more - information. If not specified the plaintext password is assumed to - be retrieved. Not required unless userPassword is - specified

- - - -

How do we handle JNDI referrals? Allowed values are - "ignore", "follow", or "throw" (see javax.naming.Context.REFERRAL - for more information). - Microsoft Active Directory often returns referrals. - If you need to follow them set referrals to "follow". - Caution: if your DNS is not part of AD, the LDAP client lib might try - to resolve your domain name in DNS to find another LDAP server.

- - - -

A string specifying the security protocol to use. If not given - the providers default is used.

- - - -

The base directory entry for performing role searches. If - not specified, the top level element in the directory context - will be used.

- - - -

The name of the attribute that contains role names in the - directory entries found by a role search. In addition you can - use the userRoleName property to specify the name - of an attribute, in the user's entry, containing additional - role names. If roleName is not specified a role - search does not take place, and roles are taken only from the - user's entry.

- - - -

The LDAP filter expression used for performing role - searches, following the syntax supported by the - java.text.MessageFormat class. Use - {0} to substitute the distinguished name (DN) of - the user, and/or {1} to substitute the - username. If not specified a role search does not take place - and roles are taken only from the attribute in the user's - entry specified by the userRoleName property.

- - - -

Set to true if you want to search the entire - subtree of the element specified by the roleBase - property for role entries associated with the user. The - default value of false causes only the top level - to be searched.

- - - -

The base element for user searches performed using the - userSearch expression. If not specified, the top - level element in the directory context will be used. Not used - if you are using the userPattern expression.

- - - -

Name of the attribute in the user's entry containing the - user's password. If you specify this value, JNDIRealm will - bind to the directory using the values specified by - connectionName and - connectionPassword properties, and retrieve the - corresponding attribute for comparison to the value specified - by the user being authenticated. If the digest - attribute is set, the specified digest algorithm is applied to - the password offered by the user before comparing it with the - value retrieved from the directory. If you do - not specify this value, JNDIRealm will - attempt a simple bind to the directory using the DN of the - user's entry and password specified by the user, with a - successful bind being interpreted as an authenticated - user.

- - - -

A pattern for the distinguished name (DN) of the user's - directory entry, following the syntax supported by the - java.text.MessageFormat class with - {0} marking where the actual username should be - inserted. You can use this property instead of - userSearch, userSubtree and - userBase when the distinguished name contains the - username and is otherwise the same for all users.

- - - -

The name of an attribute in the user's directory entry - containing zero or more values for the names of roles assigned - to this user. In addition you can use the - roleName property to specify the name of an - attribute to be retrieved from individual role entries found - by searching the directory. If userRoleName is - not specified all the roles for a user derive from the role - search.

- - - -

The LDAP filter expression to use when searching for a - user's directory entry, with {0} marking where - the actual username should be inserted. Use this property - (along with the userBase and - userSubtree properties) instead of - userPattern to search the directory for the - user's entry.

- - - -

Set to true if you want to search the entire - subtree of the element specified by the userBase - property for the user's entry. The default value of - false causes only the top level to be searched. - Not used if you are using the userPattern - expression.

- - - +as described above. The attributes for the +JNDIRealm are defined in the Realm configuration +documentation.

Example

@@ -1236,33 +920,9 @@ in this file are not recognized until Tomcat is restarted.

To configure MemoryRealm, you will create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml file, -as described above. The following -attributes are supported by this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.MemoryRealm" here.

- - - -

The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - java.security.MessageDigest class. See - Digested Passwords for more - information. If not specified, passwords are stored in clear text.

- - - -

Absolute or relative (to $CATALINA_BASE) pathname of the XML document - containing our valid usernames, passwords, and roles. See below for more - information on the format of this file. If not specified, the value - conf/tomcat-users.xml is used.

- - - +as described above. The attributes for the +MemoryRealm are defined in the Realm +configuration documentation.

User File Format

@@ -1380,41 +1040,9 @@ the resources you want to protect

To configure JAASRealm as for step 6 above, you create a <Realm> element and nest it in your $CATALINA_BASE/conf/server.xml -file within your <Engine> node. The following attributes -are supported by this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.JAASRealm" here.

- - - -

The name of the application as configured in your login configuration file - (JAAS LoginConfig).

- - - -

A comma-seperated list of the names of the classes that you have made - for your user Principals.

- - - -

A comma-seperated list of the names of the classes that you have made - for your role Principals.

- - - -

Instructs JAASRealm to use the context class loader for loading the user-specified - LoginModule class and associated Principal classes. The - default value is true, which is backwards-compatible with the way - Tomcat 4 works. To load classes using the container's classloader, specify - false.

- - - +file within your <Engine> node. The attributes for the +JAASRealm are defined in the Realm +configuration documentation.

Example

@@ -1491,19 +1119,8 @@ and restarting the server, without any code changes to your application. element and nest it in your $CATALINA_BASE/conf/server.xml file within your <Engine> or <Host>. You can also nest inside a <Context> node in a - context.xml file. The following attributes are supported by - this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.CombinedRealm" here.

- - - - + context.xml file.

+

Example

Here is an example of how your server.xml snippet should look to use a @@ -1552,41 +1169,10 @@ UserDatabase Realm and a DataSource Realm.

element and nest it in your $CATALINA_BASE/conf/server.xml file within your <Engine> or <Host>. You can also nest inside a <Context> node in a - context.xml file. The following attributes are supported by - this implementation:

- - - - -

The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "org.apache.catalina.realm.LockOutRealm" here.

- - - -

If a failed user is removed from the cache because the cache is too - big before it has been in the cache for at least this period of time (in - seconds) a warning message will be logged. Defaults to 3600 (1 hour).

- - - -

Number of users that have failed authentication to keep in cache. Over - time the cache will grow to this size and may not shrink. Defaults to - 1000.

- - - -

The number of times in a row a user has to fail authentication to be - locked out. Defaults to 5.

- - - -

The time (in seconds) a user is locked out for after too many - authentication failures. Defaults to 300 (5 minutes).

- - - - + context.xml file. The attributes for the + LockOutRealm are defined in the Realm + configuration documentation.

+

Example

Here is an example of how your server.xml snippet should look to add lock out -- 2.11.0