This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/main by this push:
new 0c1915d Add UserDatabase documentation
0c1915d is described below
commit 0c1915dd188bc0180cbc918cdc3cba8d40fa7e6d
Author: remm
AuthorDate: Fri Aug 27 09:56:32 2021 +0200
Add UserDatabase documentation
---
webapps/docs/jndi-resources-howto.xml | 204 +-
1 file changed, 202 insertions(+), 2 deletions(-)
diff --git a/webapps/docs/jndi-resources-howto.xml
b/webapps/docs/jndi-resources-howto.xml
index 3888eaa..c3574c7 100644
--- a/webapps/docs/jndi-resources-howto.xml
+++ b/webapps/docs/jndi-resources-howto.xml
@@ -427,14 +427,14 @@ public class MyBean2 {
-
+
0. Introduction
UserDatabase resources are typically configured as global resources for
use by a UserDatabase realm. Tomcat includes a UserDatabaseFactory that
creates UserDatabase resources backed by an XML file - usually
-tomcat-users.xml
+tomcat-users.xml.
The steps required to set up a global UserDatabase resource are
described
below.
@@ -495,6 +495,206 @@ public class MyBean2 {
+
+
+0. Introduction
+
+Tomcat also include a UserDatabase that uses a
+DataSource resource as the backend. The backend resource
+must be declared in the same JNDI context as the user database that will
use
+it.
+
+The steps required to set up a global UserDatabase resource are
described
+below.
+
+1. Database schema
+
+The database shema for the user database is flexible. It can be the same
+as the schema used for the DataSourceRealm, with only a table
+for users (user name, password), and another one listing the roles
+associated with each user. To support the full UserDatabase
+features, it must include additional tables for groups, and is
+compatible with referential integrity between users, groups and roles.
+
+The full featured schema with groups and referential integrity
+could be:
+
+
+
+The minimal schema without the ability to use groups will be
+(it is the same as for the DataSourceRealm):
+
+
+
+2. Declare Your Resource
+
+Next, modify $CATALINA_BASE/conf/server.xml to create the
+UserDatabase resource based on your DataSource and its schema.
+It should look something like this:
+
+
+
+The dataSourceName attribute is the JNDI name of the
+DataSource that will be the backend for the
+UserDatabase. It must be declared in the same JNDI
+Context as the UserDatabase. Please refer to the
+DataSource resources
+documentation for further instructions.
+
+The readonly attribute is optional and defaults to
+true if not supplied. If the database is writeable then
changes
+made through the Tomcat management to the UserDatabase can
+be persisted to the database using the save operation.
+
+Alternately, changes can also be made directly to the backend database.
+
+
+3. Resource configuration
+
+
+
+
+The name of the JNDI JDBC DataSource for this UserDatabase.
+
+
+
+Name of the column, in the "groups", "group roles" and "user groups"
+tables, that contains the group's name.
+
+
+
+Name of the "group roles" table, which must contain columns
+named by the groupNameCol and roleNameCol
+attributes.
+
+
+
+Name of the "groups" table, which must contain columns named
+by the groupNameCol attribute.
+
+
+
+If this is set to true, then changes to the
+UserDatabase can be persisted to the
+DataSource by using the save method.
+The default value is false.
+
+
+
+Name of the column, in the "roles" and "groups" tables, that
contains
+the description for the roles and groups.
+
+
+
+Name of the column, in the "roles", "user roles" and "group roles"
+tables, which contains a role name assigned to the corresponding
+user.
+
+
+
+Name of the "roles" table, which must contain columns named
+by the roleNameCol attribute.
+
+
+
+Name of the column, in the "users" table, which contains
+the user's credentials (i.e. password). If a
+CredentialHandler 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.
+
+
+
+Name of the "user groups" table, which must contain columns
+named by the userNameCol and groupNameCol
+attributes.
+
+
+
+Name of the column, in the "users", "user groups" and "user roles"
+tables, that contains the user's user
