From aed8aa22fd9e388af9999cf70931639845eda1a0 Mon Sep 17 00:00:00 2001 From: markt Date: Thu, 10 Dec 2009 18:46:39 +0000 Subject: [PATCH] Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=47507 Document the UserDatabaseRealm, in particular the readonly attribute of UserDartabase resources. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@889363 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/config/realm.xml | 25 ++++++++++ webapps/docs/jndi-resources-howto.xml | 65 ++++++++++++++++++++++++++ webapps/docs/realm-howto.xml | 87 ++++++++++++++++++++++++++++------- 3 files changed, 161 insertions(+), 16 deletions(-) diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml index 2191c7914..540a46504 100644 --- a/webapps/docs/config/realm.xml +++ b/webapps/docs/config/realm.xml @@ -478,6 +478,31 @@ JNDI Directory Realm component.

+

UserDatabase Realm (org.apache.catalina.realm.UserDatabaseRealm)

+ +

The UserDatabase Realm is a Realm implementation + that is based on a UserDatabase resource made available through the global + JNDI resources configured for this Tomcat instance.

+ +

The Memory Based Realm implementation supports the following + additional attributes:

+ + + + +

The name of the resource that this realm will use for user, password + and role information.

+ + + + +

See the + Container-Managed Security Guide for more + information on setting up container managed security using the UserDatabase + Realm component and the + JNDI resources how-to for more + information on how to configure a UserDatabase resource.

+

Memory Based Realm (org.apache.catalina.realm.MemoryRealm)

The Memory Based Realm is a simple Realm implementation diff --git a/webapps/docs/jndi-resources-howto.xml b/webapps/docs/jndi-resources-howto.xml index 64f0be327..b9b98d453 100644 --- a/webapps/docs/jndi-resources-howto.xml +++ b/webapps/docs/jndi-resources-howto.xml @@ -309,6 +309,71 @@ writer.println("foo = " + bean.getFoo() + ", bar = " + + + +

0. Introduction

+ +

UserDatabase resources are typically configured as global resources for + use by a UserDatabase realm. Tomcat includes a UserDatabaseFactoory that + creates UserDatabase resources backed by an XML file - usually + tomcat-users.xml

+ +

The steps required to set up a global UserDatabase resource are described + below.

+ +

1. Create/edit the XML file

+ +

The XMl file is typically located at + $CATALINA_BASE/conf/tomcat-users.xml however, you are free to + locate the file anywhere on the file system. It is recommended that the XML + files are placed in $CATALINA_BASE/conf. A typical XML would + look like:

+ + +<?xml version='1.0' encoding='utf-8'?> +<tomcat-users> + <role rolename="tomcat"/> + <role rolename="role1"/> + <user username="tomcat" password="tomcat" roles="tomcat"/> + <user username="both" password="tomcat" roles="tomcat,role1"/> + <user username="role1" password="tomcat" roles="role1"/> +</tomcat-users> + + +

2. Declare Your Resource

+ +

Next, modify $CATALINA_BASE/conf/server.xml to create the + UserDatabase resource based on your XMl file. It should look something like + this:

+ + +<Resource name="UserDatabase" + auth="Container" + type="org.apache.catalina.UserDatabase" + description="User database that can be updated and saved" + factory="org.apache.catalina.users.MemoryUserDatabaseFactory" + pathname="conf/tomcat-users.xml" + readonly="false" /> + + +

The pathname attribute can be absolute or relative. If + relative, it is relative to $CATALINA_BASE.

+ +

The readonly attribute is optional and defaults to + false if not supplied. If the XML is writeable then it will be + written to when Tomcat starts. WARNING: When the file is + written it will inherit the default file permissions for the user Tomcat + is running as. Ensure that these are appropriate to maintain the security + of your installation.

+ +

3. Configure the Realm

+ +

Configure a UserDatabase Realm to use this resource as described in the + Realm configuration documentation.

+ + + +

0. Introduction

diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml index 7b5b8b479..ea0c3095a 100644 --- a/webapps/docs/realm-howto.xml +++ b/webapps/docs/realm-howto.xml @@ -119,6 +119,9 @@ sources of authentication information:

  • JNDIRealm - Accesses authentication information stored in an LDAP based directory server, accessed via a JNDI provider.
    • +
  • UserDatabaseRealm - Accesses authentication + information stored in an UserDatabase JNDI resource, which is typically + backed by an XML document (conf/tomcat-users.xml).
  • MemoryRealm - Accesses authentication information stored in an in-memory object collection, which is initialized from an XML document (conf/tomcat-users.xml).
    • @@ -261,7 +264,7 @@ protected by a security constraint, utilizing form-based login. To access it, point your browser at http://localhost:8080/examples/jsp/security/protected/ and log on with one of the usernames and passwords described for the default -MemoryRealm.

    +UserDatabaseRealm.

     @@ -906,6 +909,71 @@ authentication is usually to be preferred.

    + + +

    Introduction

    + +

    UserDatabaseRealm is an implementation of the Tomcat 6 +Realm interface that uses a JNDI resource to store user +information. By default, the JNDI resource is backed by an XML file. It is not +designed for large-scale production use. At startup time, the UserDatabaseRealm +loads information about all users, and their corresponding roles, from an XML +document (by default, this document is loaded from +$CATALINA_BASE/conf/tomcat-users.xml). The users, their passwords +and their roles may all be editing dynamically, typically via JMX. Changes may +be saved and will be reflected in the XMl file.

    + +

    Realm Element Attributes

    + +

    To configure UserDatabaseRealm, you will create a <Realm> +element and nest it in your $CATALINA_BASE/conf/server.xml file, +as described above. The attributes for the +UserDatabaseRealm are defined in the Realm +configuration documentation.

    + +

    User File Format

    + +

    The users file uses the same format as the +MemoryRealm.

    + +

    Example

    + +

    The default installation of Tomcat 6 is configured with a UserDatabaseRealm +nested inside the <Engine> element, so that it applies +to all virtual hosts and web applications. The default contents of the +conf/tomcat-users.xml file is:

    + +<tomcat-users> + <user name="tomcat" password="tomcat" roles="tomcat" /> + <user name="role1" password="tomcat" roles="role1" /> + <user name="both" password="tomcat" roles="tomcat,role1" /> +</tomcat-users> + + +

    Additional Notes

    + +

    UserDatabaseRealm operates according to the following rules:

    + + + +     + +

    Introduction

    @@ -913,7 +981,8 @@ authentication is usually to be preferred.

    MemoryRealm is a simple demonstration implementation of the Tomcat 6 Realm interface. It is not designed for production use. At startup time, MemoryRealm loads information about all users, and their -corresponding roles, from an XML document (by default, this document is loaded from $CATALINA_BASE/conf/tomcat-users.xml). Changes to the data +corresponding roles, from an XML document (by default, this document is loaded +from $CATALINA_BASE/conf/tomcat-users.xml). Changes to the data in this file are not recognized until Tomcat is restarted.

    Realm Element Attributes

    @@ -940,20 +1009,6 @@ valid user, consisting of the following attributes:

    associated with this user. -

    Example

    - -

    The default installation of Tomcat 6 is configured with a MemoryRealm -nested inside the <Engine> element, so that it applies -to all virtual hosts and web applications. The default contents of the -conf/tomcat-users.xml file is:

    - -<tomcat-users> - <user name="tomcat" password="tomcat" roles="tomcat" /> - <user name="role1" password="tomcat" roles="role1" /> - <user name="both" password="tomcat" roles="tomcat,role1" /> -</tomcat-users> - -

    Additional Notes

    MemoryRealm operates according to the following rules:

    -- 2.11.0