Dear Wiki user, You have subscribed to a wiki page or wiki category on "Tomcat Wiki" for change notification.
The "TomcatDataSourceRealms" page has been changed by KonstantinKolinko: http://wiki.apache.org/tomcat/TomcatDataSourceRealms?action=diff&rev1=1&rev2=2 Comment: Add category link, s/CATALINA_HOME/CATALINA_BASE/ * [[http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html#JDBC%20Data%20Sources|JDBC Data Sources]] === IMPORTANT NOTE === - Using a JNDI JDBC data source resource requires the JDBC driver to be visible to Tomcat. Thus, the JDBC driver needs to be placed in $CATALINA_HOME/lib (for Tomcat 6). Once this is done, '''do not put this driver in the application's WEB-INF/lib directory'''. + Using a JNDI JDBC data source resource requires the JDBC driver to be visible to Tomcat. Thus, the JDBC driver needs to be placed in $CATALINA_BASE/lib (for Tomcat 6). Once this is done, '''do not put this driver in the application's WEB-INF/lib directory'''. The second component is the actual Realm. Documentation for setting this up can be found in the following locations: @@ -91, +91 @@ * Everything in META-INF/context.xml which provides an application - specific configuration * !GlobalNamingResources and META-INF/context.xml which provides for multiple applications selectively using authentication - * Everything in $CATALINA_HOME/conf/server.xml which provides a global Host or Engine configuration + * Everything in $CATALINA_BASE/conf/server.xml which provides a global Host or Engine configuration == Everything in META-INF/context.xml == This is appropriate when each web application might use different authentication and authorization databases. This is also the simplest configuration to manage, since all configuration elements are in one location. Finally, this configuration will produce the most portable (between Tomcat installations) war file. @@ -170, +170 @@ 1. Add Resource element to META-INF/context.xml 1. Add Realm element to META-INF/context.xml - == Resource in $CATALINA_HOME/conf/server.xml and Realm in META-INF/context.xml == + == Resource in $CATALINA_BASE/conf/server.xml and Realm in META-INF/context.xml == - This configuration can be appropriate when multiple applications need to use the same authentication and authorization database. The JNDI resource is described in the !GlobalNamingResources element of $CATALINA_HOME/conf/server.xml. Each application that requires authentication and authorization via this resource should a Realm definition in META-INF/context.xml referencing the global name. + This configuration can be appropriate when multiple applications need to use the same authentication and authorization database. The JNDI resource is described in the !GlobalNamingResources element of $CATALINA_BASE/conf/server.xml. Each application that requires authentication and authorization via this resource should a Realm definition in META-INF/context.xml referencing the global name. === Resource Element === The Resource element used in the !GlobalNamingResources is the same one that is described above. The only difference is its placement. Below is the default !GlobalNamingResources element (without comments) as shipped with Tomcat 6. @@ -185, +185 @@ pathname="conf/tomcat-users.xml" /> </GlobalNamingResources> }}} - Adding the authentication and authorization resource to the above default implementation creates the following !GlobalNamingResources element in $CATALINA_HOME/conf/server.xml. + Adding the authentication and authorization resource to the above default implementation creates the following !GlobalNamingResources element in $CATALINA_BASE/conf/server.xml. {{{ <GlobalNamingResources> @@ -210, +210 @@ }}} This entry makes the authentication and authorization database available to all applications by referencing the JNDI name jdbc/auth. - '''NOTE:''' In order to make the new Resource available, Tomcat will have to be restarted once the $CATALINA_HOME/conf/server.xml file has been modified. + '''NOTE:''' In order to make the new Resource available, Tomcat will have to be restarted once the $CATALINA_BASE/conf/server.xml file has been modified. === Realm Element === Finally, in order for the web application to use this authentication and authorization resource, a Realm element needs to be added to META-INF/context.xml. An example is shown below. @@ -227, +227 @@ Items to note are listed below. * '''localDataSource="true"''' is no longer present, since the Resource is no longer local. - * '''dataSourceName''' refers to the name of the Resource element in $CATALINA_HOME/conf/server.xml + * '''dataSourceName''' refers to the name of the Resource element in $CATALINA_BASE/conf/server.xml === Completed META-INF/context.xml === The completed META-INF/context.xml file is shown below. @@ -246, +246 @@ }}} === Summary for GlobalNamingResources and META-INF/context.xml === 1. Add security constraints and information to WEB-INF/web.xml - 1. Modify $CATALINA_HOME/conf/server.xml + 1. Modify $CATALINA_BASE/conf/server.xml 1. Add the Resource sub-element to !GlobalNamingResources 1. Restart Tomcat to make the new Resource availale 1. Add the Realm element to '''each''' META-INF/context.xml that requires authentication and authorization - == Resource and Realm in $CATALINA_HOME/conf/server.xml == + == Resource and Realm in $CATALINA_BASE/conf/server.xml == - Sometimes every sub-element under a particular element requires the same set of authentication and authorization resources. Rather than duplicating the configuration for multiple resources, it may make sense to place both the Resource and Realm in $CATALINA_HOME/conf/server.xml. Possible scenarios are listed below. + Sometimes every sub-element under a particular element requires the same set of authentication and authorization resources. Rather than duplicating the configuration for multiple resources, it may make sense to place both the Resource and Realm in $CATALINA_BASE/conf/server.xml. Possible scenarios are listed below. * Resource in !GlobalNamingResources and Realm in a Host element * The Resource provides the authentication and authorization JNDI resource to all components @@ -261, +261 @@ * The Resource provides the authentication and authorization JNDI resource to all components * The Realm makes authentication and authorization information available to all hosts and applications under the Engine - Each web application that wishes to make use of the $CATALINA_HOME/conf/server.xml - defined Realm must still obviously have security constraints configured in WEB-INF/web.xml.''' ''' + Each web application that wishes to make use of the $CATALINA_BASE/conf/server.xml - defined Realm must still obviously have security constraints configured in WEB-INF/web.xml.''' ''' === Cascading Realms === Tomcat resolves multiple Realm definitions by using the most specific one for a given element. Examples are given below. - * Realm definition in the Engine element of $CATALINA_HOME/conf/server.xml + * Realm definition in the Engine element of $CATALINA_BASE/conf/server.xml * Would be overridden by a Realm definition in a Host sub-element of the Engine element * Would be overridden by a Realm definition in the META-INF/context.xml for a particular application - * Realm definition in the Host element of $CATALINA_HOME/conf/server.xml + * Realm definition in the Host element of $CATALINA_BASE/conf/server.xml * Would be overridden by a Realm definition in the META-INF/context.xml for a particular application === CombinedRealm === - One way to manage multiple Realms in $CATALINA_HOME/conf/server.xml is to use a !CombinedRealm. The !CombinedRealm provides a container for other Realms (sub-Realms). These Realms are '''tried in the order configured''', until an authentication match is is made or all sub-Realms are tried. + One way to manage multiple Realms in $CATALINA_BASE/conf/server.xml is to use a !CombinedRealm. The !CombinedRealm provides a container for other Realms (sub-Realms). These Realms are '''tried in the order configured''', until an authentication match is is made or all sub-Realms are tried. Care should be taken that authentication and authorization information '''does not unintentionally overlap'''. Some of the consequences are discussed below. @@ -287, +287 @@ There are also benefits to this approach. One sub-Realm could be used as an "administrator" Realm, while other sub-Realms could provide authentication and authorization for specific applications. === Configuration Using CombinedRealm === - The following steps can be used to configure a !DataSource Realm in $CATALINA/conf/server.xml using a !CombinedRealm. + The following steps can be used to configure a !DataSource Realm in $CATALINA_BASE/conf/server.xml using a !CombinedRealm. ==== Resource Element ==== - Add the required Resource element to the !GlobalNamingResources element in $CATALINA_HOME/conf/server.xml. Below is the default !GlobalNamingResources element (without comments) as shipped with Tomcat 6. + Add the required Resource element to the !GlobalNamingResources element in $CATALINA_BASE/conf/server.xml. Below is the default !GlobalNamingResources element (without comments) as shipped with Tomcat 6. {{{ <GlobalNamingResources> @@ -301, +301 @@ pathname="conf/tomcat-users.xml" /> </GlobalNamingResources> }}} - Adding the authentication and authorization resource to the above default implementation creates the following !GlobalNamingResources element in $CATALINA_HOME/conf/server.xml. + Adding the authentication and authorization resource to the above default implementation creates the following !GlobalNamingResources element in $CATALINA_BASE/conf/server.xml. {{{ <GlobalNamingResources> @@ -326, +326 @@ }}} This entry makes the authentication and authorization database available to all applications by referencing the JNDI name jdbc/auth. - '''NOTE:''' In order to make the new Resource available, Tomcat will have to be restarted once the $CATALINA_HOME/conf/server.xml file has been modified. + '''NOTE:''' In order to make the new Resource available, Tomcat will have to be restarted once the $CATALINA_BASE/conf/server.xml file has been modified. ==== Realm Element ==== - In order to avoid overriding the existing Engine-level Realm element in Tomcat's default $CATALINA_HOME/conf/server.xml, a !CombinedRealm container will be used. + In order to avoid overriding the existing Engine-level Realm element in Tomcat's default $CATALINA_BASE/conf/server.xml, a !CombinedRealm container will be used. First, here is the default Realm as shipped with Tomcat 6. @@ -337, +337 @@ <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/> }}} - Surround this Realm element with another Realm element defining the !CombinedRealm. Within that element place both the default Tomcat !UserDatabaseRealm and the !DataSourceRealm. The resulting section of $CATALINA/conf/server.xml will look like the following. + Surround this Realm element with another Realm element defining the !CombinedRealm. Within that element place both the default Tomcat !UserDatabaseRealm and the !DataSourceRealm. The resulting section of $CATALINA_BASE/conf/server.xml will look like the following. {{{ <Realm className="org.apache.catalina.realm.CombinedRealm"> @@ -352, +352 @@ dataSourceName="jdbc/auth"/> </Realm> }}} - '''NOTE:''' With both Realm and Resource information in $CATALINA_HOME/conf/server.xml, no Realm or Resource elements pertaining to authorization and authentication should appear in META-INF/context.xml. An application may require other Resource elements, but any Realm element in META-INF/context.xml will '''override''' that provided in $CATALINA_HOME/conf/server.xml. + '''NOTE:''' With both Realm and Resource information in $CATALINA_BASE/conf/server.xml, no Realm or Resource elements pertaining to authorization and authentication should appear in META-INF/context.xml. An application may require other Resource elements, but any Realm element in META-INF/context.xml will '''override''' that provided in $CATALINA_BASE/conf/server.xml. - ==== Summary for Resource and Realm in $CATALINA_HOME/conf/server.xml ==== + ==== Summary for Resource and Realm in $CATALINA_BASE/conf/server.xml ==== 1. Add security constraints to the application's WEB-INF/web.xml - 1. Add the JNDI resource to !GlobalNamingResources in $CATALINA_HOME/conf/server.xml + 1. Add the JNDI resource to !GlobalNamingResources in $CATALINA_BASE/conf/server.xml - 1. Create a !CombinedRealm at the appropriate level in $CATALINA_HOME/conf/server.xml (Engine is used in this example) + 1. Create a !CombinedRealm at the appropriate level in $CATALINA_BASE/conf/server.xml (Engine is used in this example) 1. Add the existing !UserDatabaseRealm to the !CombinedRealm as a sub-Realm 1. Add the !DataSourceRealm to the !CombinedRealm as a sub-Realm - 1. Restart Tomcat to read the configuration changes in $CATALINA_HOME/conf/server.xml + 1. Restart Tomcat to read the configuration changes in $CATALINA_BASE/conf/server.xml == Summary == The following outline summarizes the three approaches discussed above. @@ -369, +369 @@ 1. Add the Resource element describing the JNDI datasource 1. Add the !DataSourceRealm element 1. add localDataSource="true" to reference the local JNDI datasource - 1. Resource in $CATALINA_HOME/conf/server.xml and Realm in META-INF/context.xml + 1. Resource in $CATALINA_BASE/conf/server.xml and Realm in META-INF/context.xml - 1. Add the Resource element describing the JNDI datasource to !GlobalNamingResources in $CATALINA_HOME/conf/server.xml + 1. Add the Resource element describing the JNDI datasource to !GlobalNamingResources in $CATALINA_BASE/conf/server.xml 1. Restart Tomcat to read the new Resource 1. Add the !DataSourceRealm element to the application's META-INF/context.xml - 1. Resource and Realm in $CATALINA_HOME/conf/server.xml + 1. Resource and Realm in $CATALINA_BASE/conf/server.xml - 1. Add the Resource element describing the JNDI datasource to !GlobalNamingResources in $CATALINA_HOME/conf/server.xml + 1. Add the Resource element describing the JNDI datasource to !GlobalNamingResources in $CATALINA_BASE/conf/server.xml - 1. Add a !CombinedRealm Realm element the the Engine element of $CATALINA_HOME/conf/server.xml + 1. Add a !CombinedRealm Realm element the the Engine element of $CATALINA_BASE/conf/server.xml 1. Place the exisitng !UserDatabaseRealm inside this !CombinedRealm Realm element 1. Place the application's !DataSourceRealm inside this !CombinedRealm Realm element - 1. Restart Tomcat to read the new $CATALINA_HOME/conf/server.xml + 1. Restart Tomcat to read the new $CATALINA_BASE/conf/server.xml 1. Make sure that no overriding Realms or Resources are present in the application's META-INF/context.xml file + ---- + [[CategoryFAQ]] + --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
