Return-Path: X-Original-To: apmail-tomcat-dev-archive@www.apache.org Delivered-To: apmail-tomcat-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 0DAEBED87 for ; Sat, 2 Feb 2013 23:11:54 +0000 (UTC) Received: (qmail 58879 invoked by uid 500); 2 Feb 2013 23:11:53 -0000 Delivered-To: apmail-tomcat-dev-archive@tomcat.apache.org Received: (qmail 58786 invoked by uid 500); 2 Feb 2013 23:11:53 -0000 Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Tomcat Developers List" Delivered-To: mailing list dev@tomcat.apache.org Received: (qmail 58777 invoked by uid 99); 2 Feb 2013 23:11:53 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 Feb 2013 23:11:53 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.131] (HELO eos.apache.org) (140.211.11.131) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 Feb 2013 23:11:48 +0000 Received: from eos.apache.org (localhost [127.0.0.1]) by eos.apache.org (Postfix) with ESMTP id 74C195D5 for ; Sat, 2 Feb 2013 23:11:27 +0000 (UTC) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable From: Apache Wiki To: Apache Wiki Date: Sat, 02 Feb 2013 23:11:27 -0000 Message-ID: <20130202231127.81311.43991@eos.apache.org> Subject: =?utf-8?q?=5BTomcat_Wiki=5D_Update_of_=22TomcatDataSourceRealms=22_by_Kon?= =?utf-8?q?stantinKolinko?= Auto-Submitted: auto-generated X-Virus-Checked: Checked by ClamAV on apache.org Dear Wiki user, You have subscribed to a wiki page or wiki category on "Tomcat Wiki" for ch= ange notification. The "TomcatDataSourceRealms" page has been changed by KonstantinKolinko: http://wiki.apache.org/tomcat/TomcatDataSourceRealms?action=3Ddiff&rev1=3D1= &rev2=3D2 Comment: Add category link, s/CATALINA_HOME/CATALINA_BASE/ * [[http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html#JD= BC%20Data%20Sources|JDBC Data Sources]] = =3D=3D=3D IMPORTANT NOTE =3D=3D=3D - Using a JNDI JDBC data source resource requires the JDBC driver to be vis= ible 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 app= lication's WEB-INF/lib directory'''. + Using a JNDI JDBC data source resource requires the JDBC driver to be vis= ible 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 app= lication'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 - spe= cific configuration * !GlobalNamingResources and META-INF/context.xml which provides for mul= tiple applications selectively using authentication - * Everything in $CATALINA_HOME/conf/server.xml which provides a global H= ost or Engine configuration + * Everything in $CATALINA_BASE/conf/server.xml which provides a global H= ost or Engine configuration = =3D=3D Everything in META-INF/context.xml =3D=3D This is appropriate when each web application might use different authent= ication and authorization databases. This is also the simplest configuratio= n to manage, since all configuration elements are in one location. Finally,= this configuration will produce the most portable (between Tomcat installa= tions) war file. @@ -170, +170 @@ 1. Add Resource element to META-INF/context.xml 1. Add Realm element to META-INF/context.xml = - =3D=3D Resource in $CATALINA_HOME/conf/server.xml and Realm in META-INF/c= ontext.xml =3D=3D + =3D=3D Resource in $CATALINA_BASE/conf/server.xml and Realm in META-INF/c= ontext.xml =3D=3D - This configuration can be appropriate when multiple applications need to = use the same authentication and authorization database. The JNDI resource i= s described in the !GlobalNamingResources element of $CATALINA_HOME/conf/se= rver.xml. Each application that requires authentication and authorization v= ia this resource should a Realm definition in META-INF/context.xml referenc= ing the global name. + This configuration can be appropriate when multiple applications need to = use the same authentication and authorization database. The JNDI resource i= s described in the !GlobalNamingResources element of $CATALINA_BASE/conf/se= rver.xml. Each application that requires authentication and authorization v= ia this resource should a Realm definition in META-INF/context.xml referenc= ing the global name. = =3D=3D=3D Resource Element =3D=3D=3D The Resource element used in the !GlobalNamingResources is the same one t= hat is described above. The only difference is its placement. Below is the = default !GlobalNamingResources element (without comments) as shipped with T= omcat 6. @@ -185, +185 @@ pathname=3D"conf/tomcat-users.xml" /> }}} - Adding the authentication and authorization resource to the above default= implementation creates the following !GlobalNamingResources element in $CA= TALINA_HOME/conf/server.xml. + Adding the authentication and authorization resource to the above default= implementation creates the following !GlobalNamingResources element in $CA= TALINA_BASE/conf/server.xml. = {{{ @@ -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 modi= fied. + '''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 modi= fied. = =3D=3D=3D Realm Element =3D=3D=3D Finally, in order for the web application to use this authentication and = authorization resource, a Realm element needs to be added to META-INF/conte= xt.xml. An example is shown below. @@ -227, +227 @@ Items to note are listed below. = * '''localDataSource=3D"true"''' is no longer present, since the Resourc= e is no longer local. - * '''dataSourceName''' refers to the name of the Resource element in $CA= TALINA_HOME/conf/server.xml + * '''dataSourceName''' refers to the name of the Resource element in $CA= TALINA_BASE/conf/server.xml = =3D=3D=3D Completed META-INF/context.xml =3D=3D=3D The completed META-INF/context.xml file is shown below. @@ -246, +246 @@ }}} =3D=3D=3D Summary for GlobalNamingResources and META-INF/context.xml =3D= =3D=3D 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 require= s authentication and authorization = - =3D=3D Resource and Realm in $CATALINA_HOME/conf/server.xml =3D=3D + =3D=3D Resource and Realm in $CATALINA_BASE/conf/server.xml =3D=3D - 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 t= he 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 t= he 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 resou= rce to all components @@ -261, +261 @@ * The Resource provides the authentication and authorization JNDI resou= rce to all components * The Realm makes authentication and authorization information availabl= e to all hosts and applications under the Engine = - Each web application that wishes to make use of the $CATALINA_HOME/conf/s= erver.xml - defined Realm must still obviously have security constraints co= nfigured in WEB-INF/web.xml.''' ''' + Each web application that wishes to make use of the $CATALINA_BASE/conf/s= erver.xml - defined Realm must still obviously have security constraints co= nfigured in WEB-INF/web.xml.''' ''' = =3D=3D=3D Cascading Realms =3D=3D=3D 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.x= ml + * Realm definition in the Engine element of $CATALINA_BASE/conf/server.x= ml * Would be overridden by a Realm definition in a Host sub-element of th= e 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 = =3D=3D=3D CombinedRealm =3D=3D=3D - One way to manage multiple Realms in $CATALINA_HOME/conf/server.xml is to= use a !CombinedRealm. The !CombinedRealm provides a container for other Re= alms (sub-Realms). These Realms are '''tried in the order configured''', un= til 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 Re= alms (sub-Realms). These Realms are '''tried in the order configured''', un= til 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 discusse= d 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 authenticati= on and authorization for specific applications. = =3D=3D=3D Configuration Using CombinedRealm =3D=3D=3D - The following steps can be used to configure a !DataSource Realm in $CATA= LINA/conf/server.xml using a !CombinedRealm. + The following steps can be used to configure a !DataSource Realm in $CATA= LINA_BASE/conf/server.xml using a !CombinedRealm. = =3D=3D=3D=3D Resource Element =3D=3D=3D=3D - Add the required Resource element to the !GlobalNamingResources element i= n $CATALINA_HOME/conf/server.xml. Below is the default !GlobalNamingResour= ces element (without comments) as shipped with Tomcat 6. + Add the required Resource element to the !GlobalNamingResources element i= n $CATALINA_BASE/conf/server.xml. Below is the default !GlobalNamingResour= ces element (without comments) as shipped with Tomcat 6. = {{{ @@ -301, +301 @@ pathname=3D"conf/tomcat-users.xml" /> }}} - Adding the authentication and authorization resource to the above defaul= t implementation creates the following !GlobalNamingResources element in $= CATALINA_HOME/conf/server.xml. + Adding the authentication and authorization resource to the above defaul= t implementation creates the following !GlobalNamingResources element in $= CATALINA_BASE/conf/server.xml. = {{{ @@ -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 hav= e to be restarted once the $CATALINA_HOME/conf/server.xml file has been mo= dified. + '''NOTE:''' In order to make the new Resource available, Tomcat will hav= e to be restarted once the $CATALINA_BASE/conf/server.xml file has been mo= dified. = =3D=3D=3D=3D Realm Element =3D=3D=3D=3D - In order to avoid overriding the existing Engine-level Realm element in T= omcat'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 T= omcat'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 @@ }}} - Surround this Realm element with another Realm element defining the !Comb= inedRealm. Within that element place both the default Tomcat !UserDatabaseR= ealm and the !DataSourceRealm. The resulting section of $CATALINA/conf/serv= er.xml will look like the following. + Surround this Realm element with another Realm element defining the !Comb= inedRealm. Within that element place both the default Tomcat !UserDatabaseR= ealm and the !DataSourceRealm. The resulting section of $CATALINA_BASE/conf= /server.xml will look like the following. = {{{ @@ -352, +352 @@ dataSourceName=3D"jdbc/auth"/> }}} - '''NOTE:''' With both Realm and Resource information in $CATALINA_HOME/co= nf/server.xml, no Realm or Resource elements pertaining to authorization an= d 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/co= nf/server.xml, no Realm or Resource elements pertaining to authorization an= d 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. = - =3D=3D=3D=3D Summary for Resource and Realm in $CATALINA_HOME/conf/server= .xml =3D=3D=3D=3D + =3D=3D=3D=3D Summary for Resource and Realm in $CATALINA_BASE/conf/server= .xml =3D=3D=3D=3D 1. Add security constraints to the application's WEB-INF/web.xml - 1. Add the JNDI resource to !GlobalNamingResources in $CATALINA_HOME/con= f/server.xml + 1. Add the JNDI resource to !GlobalNamingResources in $CATALINA_BASE/con= f/server.xml - 1. Create a !CombinedRealm at the appropriate level in $CATALINA_HOME/co= nf/server.xml (Engine is used in this example) + 1. Create a !CombinedRealm at the appropriate level in $CATALINA_BASE/co= nf/server.xml (Engine is used in this example) 1. Add the existing !UserDatabaseRealm to the !CombinedRealm as a sub-R= ealm 1. Add the !DataSourceRealm to the !CombinedRealm as a sub-Realm - 1. Restart Tomcat to read the configuration changes in $CATALINA_HOME/co= nf/server.xml + 1. Restart Tomcat to read the configuration changes in $CATALINA_BASE/co= nf/server.xml = =3D=3D Summary =3D=3D 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=3D"true" to reference the local JNDI datasource - 1. Resource in $CATALINA_HOME/conf/server.xml and Realm in META-INF/cont= ext.xml + 1. Resource in $CATALINA_BASE/conf/server.xml and Realm in META-INF/cont= ext.xml - 1. Add the Resource element describing the JNDI datasource to !GlobalNa= mingResources in $CATALINA_HOME/conf/server.xml + 1. Add the Resource element describing the JNDI datasource to !GlobalNa= mingResources 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/conte= xt.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 !GlobalNa= mingResources in $CATALINA_HOME/conf/server.xml + 1. Add the Resource element describing the JNDI datasource to !GlobalNa= mingResources in $CATALINA_BASE/conf/server.xml - 1. Add a !CombinedRealm Realm element the the Engine element of $CATALI= NA_HOME/conf/server.xml + 1. Add a !CombinedRealm Realm element the the Engine element of $CATALI= NA_BASE/conf/server.xml 1. Place the exisitng !UserDatabaseRealm inside this !CombinedRealm Re= alm 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]] +=20 --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org For additional commands, e-mail: dev-help@tomcat.apache.org