Produced by Araxis Merge on 5/25/2018 9:21:44 AM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.
| # | Location | File | Last Modified |
|---|---|---|---|
| 1 | C:\AraxisMergeCompare\Pri_un\ZIP\DSM-cif\Direct Implementation\java\install\build\download\apache-tomcat-6.0.37.tar\apache-tomcat-6.0.37\webapps\docs | realm-howto.html | Mon Apr 29 09:36:10 2013 UTC |
| 2 | C:\AraxisMergeCompare\Pri_re\ZIP\DSM-cif\Direct Implementation\java\install\build\download\apache-tomcat-6.0.37.tar\apache-tomcat-6.0.37\webapps\docs | realm-howto.html | Thu May 24 19:55:17 2018 UTC |
| Description | Between Files 1 and 2 |
|
|---|---|---|
| Text Blocks | Lines | |
| Unchanged | 3 | 2362 |
| Changed | 2 | 6 |
| Inserted | 0 | 0 |
| Removed | 0 | 0 |
| Whitespace | |
|---|---|
| Character case | Differences in character case are significant |
| Line endings | Differences in line endings (CR and LF characters) are ignored |
| CR/LF characters | Not shown in the comparison detail |
No regular expressions were active.
| 1 | <html><hea d><META ht tp-equiv=" Content-Ty pe" conten t="text/ht ml; charse t=iso-8859 -1"><title >Apache To mcat 6.0 ( 6.0.37) - Realm Conf iguration HOW-TO</ti tle><meta name="auth or" conten t="Craig R . McClanah an"><meta name="auth or" conten t="Yoav Sh apira"><me ta name="a uthor" con tent="Andr ew R. Jaqu ith"><styl e type="te xt/css" me dia="print "> | |
| 2 | .noPri nt {displa y: none;} | |
| 3 | td#mai nBody {wid th: 100%;} | |
| 4 | </st yle></head ><body bgc olor="#fff fff" text= "#000000" link="#525 D76" alink ="#525D76" vlink="#5 25D76"><ta ble border ="0" width ="100%" ce llspacing= "0"><!--PA GE HEADER- -><tr><td> <!--PROJEC T LOGO-->< a href="ht tp://tomca t.apache.o rg/"><img src="./ima ges/tomcat .gif" alig n="right" alt=" | |
| 5 | The Apache Tom cat Servle t/JSP Cont ainer | |
| 6 | " bord er="0"></a ></td><td> <h1><font face="aria l,helvetic a,sanserif ">Apache T omcat 6.0< /font></h1 ><font fac e="arial,h elvetica,s anserif">V ersion 6.0 .37, Apr 2 9 2013</fo nt></td><t d><!--APAC HE LOGO--> <a href="h ttp://www. apache.org /"><img sr c="./image s/asf-logo .gif" alig n="right" alt="Apach e Logo" bo rder="0">< /a></td></ tr></table ><table bo rder="0" w idth="100% " cellspac ing="4"><! --HEADER S EPARATOR-- ><tr><td c olspan="2" ><hr nosha de="noshad e" size="1 "></td></t r><tr><!-- LEFT SIDE NAVIGATION --><td wid th="20%" v align="top " nowrap=" nowrap" cl ass="noPri nt"><p><st rong>Links </strong>< /p><ul><li ><a href=" index.html ">Docs Hom e</a></li> <li><a hre f="http:// wiki.apach e.org/tomc at/FAQ">FA Q</a></li> </ul><p><s trong>User Guide</st rong></p>< ul><li><a href="intr oduction.h tml">1) In troduction </a></li>< li><a href ="setup.ht ml">2) Set up</a></li ><li><a hr ef="appdev /index.htm l">3) Firs t webapp</ a></li><li ><a href=" deployer-h owto.html" >4) Deploy er</a></li ><li><a hr ef="manage r-howto.ht ml">5) Man ager</a></ li><li><a href="real m-howto.ht ml">6) Rea lms and AA A</a></li> <li><a hre f="securit y-manager- howto.html ">7) Secur ity Manage r</a></li> <li><a hre f="jndi-re sources-ho wto.html"> 8) JNDI Re sources</a ></li><li> <a href="j ndi-dataso urce-examp les-howto. html">9) J DBC DataSo urces</a>< /li><li><a href="cla ss-loader- howto.html ">10) Clas sloading</ a></li><li ><a href=" jasper-how to.html">1 1) JSPs</a ></li><li> <a href="s sl-howto.h tml">12) S SL</a></li ><li><a hr ef="ssi-ho wto.html"> 13) SSI</a ></li><li> <a href="c gi-howto.h tml">14) C GI</a></li ><li><a hr ef="proxy- howto.html ">15) Prox y Support< /a></li><l i><a href= "mbeans-de scriptor-h owto.html" >16) MBean Descripto r</a></li> <li><a hre f="default -servlet.h tml">17) D efault Ser vlet</a></ li><li><a href="clus ter-howto. html">18) Clustering </a></li>< li><a href ="balancer -howto.htm l">19) Loa d Balancer </a></li>< li><a href ="connecto rs.html">2 0) Connect ors</a></l i><li><a h ref="monit oring.html ">21) Moni toring and Managemen t</a></li> <li><a hre f="logging .html">22) Logging</ a></li><li ><a href=" apr.html"> 23) APR/Na tive</a></ li><li><a href="virt ual-hostin g-howto.ht ml">24) Vi rtual Host ing</a></l i><li><a h ref="aio.h tml">25) A dvanced IO </a></li>< li><a href ="extras.h tml">26) A dditional Components </a></li>< li><a href ="maven-ja rs.html">2 7) Maveniz ed</a></li ></ul><p>< strong>Ref erence</st rong></p>< ul><li><a href="RELE ASE-NOTES. txt">Relea se Notes</ a></li><li ><a href=" config/ind ex.html">C onfigurati on</a></li ><li><a hr ef="api/in dex.html"> Javadocs</ a></li><li ><a href=" http://tom cat.apache .org/conne ctors-doc/ ">JK 1.2 D ocumentati on</a></li ></ul><p>< strong>Apa che Tomcat Developme nt</strong ></p><ul>< li><a href ="building .html">Bui lding</a>< /li><li><a href="cha ngelog.htm l">Changel og</a></li ><li><a hr ef="http:/ /wiki.apac he.org/tom cat/Tomcat Versions"> Status</a> </li><li>< a href="de velopers.h tml">Devel opers</a>< /li><li><a href="arc hitecture/ index.html ">Architec ture</a></ li><li><a href="func specs/inde x.html">Fu nctional S pecs.</a>< /li></ul>< /td><!--RI GHT SIDE M AIN BODY-- ><td width ="80%" val ign="top" align="lef t" id="mai nBody"><h1 >Apache To mcat 6.0</ h1><h2>Rea lm Configu ration HOW -TO</h2><t able borde r="0" cell spacing="0 " cellpadd ing="2"><t r><td bgco lor="#525D 76"><font color="#ff ffff" face ="arial,he lvetica.sa nserif"><a name="Tab le of Cont ents"><!-- ()--></a>< a name="Ta ble_of_Con tents"><st rong>Table of Conten ts</strong ></a></fon t></td></t r><tr><td> <blockquot e> | |
| 7 | <ul><li><a href="#Qu ick_Start" >Quick Sta rt</a></li ><li><a hr ef="#Overv iew">Overv iew</a><ol ><li><a hr ef="#What_ is_a_Realm ?">What is a Realm?< /a></li><l i><a href= "#Configur ing_a_Real m">Configu ring a Rea lm</a></li ></ol></li ><li><a hr ef="#Commo n_Features ">Common F eatures</a ><ol><li>< a href="#D igested_Pa sswords">D igested Pa sswords</a ></li><li> <a href="# Example_Ap plication" >Example A pplication </a></li>< li><a href ="#Manager _Applicati on">Manage r Applicat ion</a></l i><li><a h ref="#Real m_Logging" >Realm Log ging</a></ li></ol></ li><li><a href="#Sta ndard_Real m_Implemen tations">S tandard Re alm Implem entations< /a><ol><li ><a href=" #JDBCRealm ">JDBCReal m</a></li> <li><a hre f="#DataSo urceRealm" >DataSourc eRealm</a> </li><li>< a href="#J NDIRealm"> JNDIRealm< /a></li><l i><a href= "#UserData baseRealm" >UserDatab aseRealm</ a></li><li ><a href=" #MemoryRea lm">Memory Realm</a>< /li><li><a href="#JA ASRealm">J AASRealm</ a></li><li ><a href=" #CombinedR ealm">Comb inedRealm< /a></li><l i><a href= "#LockOutR ealm">Lock OutRealm</ a></li></o l></li></u l> | |
| 8 | </blockquo te></td></ tr></table ><table bo rder="0" c ellspacing ="0" cellp adding="2" ><tr><td b gcolor="#5 25D76"><fo nt color=" #ffffff" f ace="arial ,helvetica .sanserif" ><a name=" Quick Star t"><!--()- -></a><a n ame="Quick _Start"><s trong>Quic k Start</s trong></a> </font></t d></tr><tr ><td><bloc kquote> | |
| 9 | ||
| 10 | <p>This do cument des cribes how to config ure Tomcat to suppor t <em>cont ainer | |
| 11 | managed se curity</em >, by conn ecting to an existin g "databas e" of user names, | |
| 12 | passwords, and user roles. Yo u only nee d to care about this if you ar e using | |
| 13 | a web appl ication th at include s one or m ore | |
| 14 | <code>< security-c onstraint& gt;</code> elements, and a | |
| 15 | <code>< login-conf ig></co de> elemen t defining how users are requi red | |
| 16 | to authent icate them selves. I f you are not utiliz ing these features, you can | |
| 17 | safely ski p this doc ument.</p> | |
| 18 | ||
| 19 | <p>For fun damental b ackground informatio n about co ntainer ma naged secu rity, | |
| 20 | see the <a href="htt p://wiki.a pache.org/ tomcat/Spe cification s">Servlet | |
| 21 | Specificat ion (Versi on 2.4)</a >, Section 12.</p> | |
| 22 | ||
| 23 | <p>For inf ormation a bout utili zing the < em>Single Sign On</e m> feature of | |
| 24 | Tomcat 6 ( allowing a user to a uthenticat e themselv es once ac ross the e ntire | |
| 25 | set of web applicati ons associ ated with a virtual host), see | |
| 26 | <a href="c onfig/host .html#Sing le Sign On ">here</a> .</p> | |
| 27 | ||
| 28 | </blockquo te></td></ tr></table ><table bo rder="0" c ellspacing ="0" cellp adding="2" ><tr><td b gcolor="#5 25D76"><fo nt color=" #ffffff" f ace="arial ,helvetica .sanserif" ><a name=" Overview"> <strong>Ov erview</st rong></a>< /font></td ></tr><tr> <td><block quote> | |
| 29 | ||
| 30 | ||
| 31 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="W hat is a R ealm?"><!- -()--></a> <a name="W hat_is_a_R ealm?"><st rong>What is a Realm ?</strong> </a></font ></td></tr ><tr><td>< blockquote > | |
| 32 | ||
| 33 | <p>A <stro ng>Realm</ strong> is a "databa se" of use rnames and passwords that | |
| 34 | identify v alid users of a web applicatio n (or set of web app lications) , plus | |
| 35 | an enumera tion of th e list of <em>roles< /em> assoc iated with each vali d user. | |
| 36 | You can th ink of rol es as simi lar to <em >groups</e m> in Unix -like oper ating | |
| 37 | systems, b ecause acc ess to spe cific web applicatio n resource s is grant ed to | |
| 38 | all users possessing a particu lar role ( rather tha n enumerat ing the li st of | |
| 39 | associated usernames ). A part icular use r can have any numbe r of roles | |
| 40 | associated with thei r username .</p> | |
| 41 | ||
| 42 | <p>Althoug h the Serv let Specif ication de scribes a portable m echanism f or | |
| 43 | applicatio ns to <em> declare</e m> their s ecurity re quirements (in the | |
| 44 | <code>web. xml</code> deploymen t descript or), there is no por table API | |
| 45 | defining t he interfa ce between a servlet container and the a ssociated user | |
| 46 | and role i nformation . In many cases, ho wever, it is desirab le to "con nect" | |
| 47 | a servlet container to some ex isting aut henticatio n database or mechan ism | |
| 48 | that alrea dy exists in the pro duction en vironment. Therefor e, Tomcat 6 | |
| 49 | defines a Java inter face (<cod e>org.apac he.catalin a.Realm</c ode>) that | |
| 50 | can be imp lemented b y "plug in " componen ts to esta blish this connectio n. | |
| 51 | Five stand ard plug-i ns are pro vided, sup porting co nnections to various | |
| 52 | sources of authentic ation info rmation:</ p> | |
| 53 | <ul> | |
| 54 | <li><a hre f="#JDBCRe alm">JDBCR ealm</a> - Accesses authentica tion infor mation | |
| 55 | stored in a rela tional dat abase, acc essed via a JDBC dri ver.</li> | |
| 56 | <li><a hre f="#DataSo urceRealm" >DataSourc eRealm</a> - Accesse s authenti cation | |
| 57 | inform ation stor ed in a re lational d atabase, a ccessed vi a a named JNDI | |
| 58 | JDBC D ataSource. </li> | |
| 59 | <li><a hre f="#JNDIRe alm">JNDIR ealm</a> - Accesses authentica tion infor mation | |
| 60 | stored in an LDA P based di rectory se rver, acce ssed via a JNDI prov ider. | |
| 61 | </li> | |
| 62 | <li><a hre f="#UserDa tabaseReal m">UserDat abaseRealm </a> - Acc esses auth entication | |
| 63 | inform ation stor ed in an U serDatabas e JNDI res ource, whi ch is typi cally | |
| 64 | backed by an XML document (<code>con f/tomcat-u sers.xml</ code>).</l i> | |
| 65 | <li><a hre f="#Memory Realm">Mem oryRealm</ a> - Acces ses authen tication | |
| 66 | inform ation stor ed in an i n-memory o bject coll ection, wh ich is ini tialized | |
| 67 | from a n XML docu ment (<cod e>conf/tom cat-users. xml</code> ).</li> | |
| 68 | <li><a hre f="#JAASRe alm">JAASR ealm</a> - Accesses authentica tion infor mation | |
| 69 | throug h the Java Authentic ation & ; Authoriz ation Serv ice (JAAS) | |
| 70 | framew ork.</li> | |
| 71 | </ul> | |
| 72 | ||
| 73 | <p>It is a lso possib le to writ e your own <code>Rea lm</code> implementa tion, | |
| 74 | and integr ate it wit h Tomcat 6 . To do s o, you nee d to: | |
| 75 | <ul> | |
| 76 | <li>Impl ement <cod e>org.apac he.catalin a.Realm</c ode>,</li> | |
| 77 | <li>Plac e your com piled real m in $CATA LINA_HOME/ lib,</li> | |
| 78 | <li>Decl are your r ealm as de scribed in the "Conf iguring a Realm" sec tion below ,</li> | |
| 79 | <li>Decl are your r ealm to th e <a href= "mbeans-de scriptor-h owto.html" >MBeans De scriptor</ a>.</li> | |
| 80 | </ul> | |
| 81 | </p> | |
| 82 | ||
| 83 | </blockquo te></td></ tr></table > | |
| 84 | ||
| 85 | ||
| 86 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="C onfiguring a Realm"> <!--()-->< /a><a name ="Configur ing_a_Real m"><strong >Configuri ng a Realm </strong>< /a></font> </td></tr> <tr><td><b lockquote> | |
| 87 | ||
| 88 | <p>Before getting in to the det ails of th e standard Realm imp lementatio ns, it is | |
| 89 | important to underst and, in ge neral term s, how a R ealm is co nfigured. In | |
| 90 | general, y ou will be adding an XML eleme nt to your <code>con f/server.x ml</code> | |
| 91 | configurat ion file, that looks something like this :</p> | |
| 92 | ||
| 93 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 94 | <Realm className= "... class name for this imple mentation" | |
| 95 | ... other att ributes fo r this imp lementatio n .../> | |
| 96 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 97 | ||
| 98 | <p>The <co de><Rea lm></co de> elemen t can be n ested insi de any one of | |
| 99 | of the fol lowing <co de>Contain er</code> elements. The locat ion of the | |
| 100 | Realm elem ent has a direct imp act on the "scope" o f that Rea lm | |
| 101 | (i.e. whic h web appl ications w ill share the same a uthenticat ion inform ation): | |
| 102 | </p> | |
| 103 | <ul> | |
| 104 | <li><em>In side an &l t;Engine&g t; element </em> - Th is Realm w ill be sha red | |
| 105 | across ALL web a pplication s on ALL v irtual hos ts, UNLESS it is ove rridden | |
| 106 | by a R ealm eleme nt nested inside a s ubordinate <code>< ;Host>< /code> | |
| 107 | or <co de><Con text></ code> elem ent.</li> | |
| 108 | <li><em>In side a < ;Host> element</e m> - This Realm will be shared across | |
| 109 | ALL we b applicat ions for T HIS virtua l host, UN LESS it is overridde n | |
| 110 | by a R ealm eleme nt nested inside a s ubordinate <code>< ;Context&g t;</code> | |
| 111 | elemen t.</li> | |
| 112 | <li><em>In side a < ;Context&g t; element </em> - Th is Realm w ill be use d ONLY | |
| 113 | for TH IS web app lication.< /li> | |
| 114 | </ul> | |
| 115 | ||
| 116 | ||
| 117 | </blockquo te></td></ tr></table > | |
| 118 | ||
| 119 | ||
| 120 | </blockquo te></td></ tr></table ><table bo rder="0" c ellspacing ="0" cellp adding="2" ><tr><td b gcolor="#5 25D76"><fo nt color=" #ffffff" f ace="arial ,helvetica .sanserif" ><a name=" Common Fea tures"><!- -()--></a> <a name="C ommon_Feat ures"><str ong>Common Features< /strong></ a></font>< /td></tr>< tr><td><bl ockquote> | |
| 121 | ||
| 122 | ||
| 123 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="D igested Pa sswords">< !--()--></ a><a name= "Digested_ Passwords" ><strong>D igested Pa sswords</s trong></a> </font></t d></tr><tr ><td><bloc kquote> | |
| 124 | ||
| 125 | <p>For eac h of the s tandard <c ode>Realm< /code> imp lementatio ns, the | |
| 126 | user's pas sword (by default) i s stored i n clear te xt. In ma ny | |
| 127 | environmen ts, this i s undesira ble becaus e casual o bservers o f the | |
| 128 | authentica tion data can collec t enough i nformation to log on | |
| 129 | successful ly, and im personate other user s. To avo id this pr oblem, the | |
| 130 | standard i mplementat ions suppo rt the con cept of <e m>digestin g</em> | |
| 131 | user passw ords. Thi s allows t he stored version of the passw ords to be | |
| 132 | encoded (i n a form t hat is not easily re versible), but that the | |
| 133 | <code>Real m</code> i mplementat ion can st ill utiliz e for | |
| 134 | authentica tion.</p> | |
| 135 | ||
| 136 | <p>When a standard r ealm authe nticates b y retrievi ng the sto red | |
| 137 | password a nd compari ng it with the value presented by the us er, you | |
| 138 | can select digested passwords by specify ing the <c ode>digest </code> | |
| 139 | attribute on your <c ode><Re alm></c ode> eleme nt. The v alue for | |
| 140 | this attri bute must be one of the digest algorithm s supporte d by the | |
| 141 | <code>java .security. MessageDig est</code> class (SH A, MD2, or MD5). | |
| 142 | When you s elect this option, t he content s of the p assword th at is | |
| 143 | stored in the <code> Realm</cod e> must be the clear text versi on of the | |
| 144 | password, as digeste d by the s pecified a lgorithm.< /p> | |
| 145 | ||
| 146 | <p>When th e <code>au thenticate ()</code> method of the Realm is called, the | |
| 147 | (cleartext ) password specified by the us er is itse lf digeste d by the s ame | |
| 148 | algorithm, and the r esult is c ompared wi th the val ue returne d by the | |
| 149 | <code>Real m</code>. An equal match impl ies that t he clearte xt version of the | |
| 150 | original p assword is the same as the one presented by the us er, so tha t this | |
| 151 | user shoul d be autho rized.</p> | |
| 152 | ||
| 153 | <p>To calc ulate the digested v alue of a cleartext password, two conven ience | |
| 154 | techniques are suppo rted:</p> | |
| 155 | <ul> | |
| 156 | <li>If you are writi ng an appl ication th at needs t o calculat e digested | |
| 157 | passwo rds dynami cally, cal l the stat ic <code>D igest()</c ode> metho d of the | |
| 158 | <code> org.apache .catalina. realm.Real mBase</cod e> class, passing th e | |
| 159 | cleart ext passwo rd and the digest al gorithm na me as argu ments. Th is | |
| 160 | method will retu rn the dig ested pass word.</li> | |
| 161 | <li>If you want to e xecute a c ommand lin e utility to calcula te the dig ested | |
| 162 | passwo rd, simply execute | |
| 163 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 164 | java org.a pache.cata lina.realm .RealmBase \ | |
| 165 | -a {al gorithm} { cleartext- password} | |
| 166 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 167 | and th e digested version o f this cle artext pas sword will be return ed to | |
| 168 | standa rd output. </li> | |
| 169 | </ul> | |
| 170 | ||
| 171 | <p>If usin g digested passwords with DIGE ST authent ication, t he clearte xt used | |
| 172 | to gene rate the d igest is d ifferent a nd the dig est must u se the MD5 | |
| 173 | algorit hm. In the examples above <cod e>{clearte xt-passwor d}</code> must be | |
| 174 | replace d with <co de>{userna me}:{realm }:{clearte xt-passwor d}</code>. For | |
| 175 | example , in a dev elopment e nvironment this migh t take the form | |
| 176 | <code>t estUser:Au thenticati on require d:testPass word</code >. The val ue for | |
| 177 | <code>{ realm}</co de> is tak en from th e <code>&l t;realm-na me></co de> | |
| 178 | element of the we b applicat ion's <cod e><logi n-config&g t;</code>. If | |
| 179 | not spe cified in web.xml, t he default value of <code>Auth entication | |
| 180 | require d</code> i s used.</p > | |
| 181 | ||
| 182 | <p>To use either of the above techniques , the | |
| 183 | <code>$CAT ALINA_HOME /lib/catal ina.jar</c ode> and | |
| 184 | <code>$CAT ALINA_HOME /bin/tomca t-juli.jar </code> fi les will n eed to be | |
| 185 | on your cl ass path t o make the <code>Rea lmBase</co de> class available. | |
| 186 | </p> | |
| 187 | ||
| 188 | <p>Non-ASC II usernam es and/or passwords are suppor ted using | |
| 189 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> java org.a pache.cata lina.realm .RealmBase \ | |
| 190 | -a {al gorithm} - e {encodin g} {input} | |
| 191 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 192 | but care i s required to ensure that the non-ASCII input is | |
| 193 | correctly passed to the digest er. | |
| 194 | The digest er returns <code>{in put}:{dige st}</code> . If the i nput appea rs | |
| 195 | corrupted in the ret urn, the d igest will be invali d.</p> | |
| 196 | ||
| 197 | </blockquo te></td></ tr></table > | |
| 198 | ||
| 199 | ||
| 200 | ||
| 201 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="E xample App lication"> <!--()-->< /a><a name ="Example_ Applicatio n"><strong >Example A pplication </strong>< /a></font> </td></tr> <tr><td><b lockquote> | |
| 202 | ||
| 203 | <p>The exa mple appli cation shi pped with Tomcat 6 i ncludes an area that is | |
| 204 | protected by a secur ity constr aint, util izing form -based log in. To ac cess it, | |
| 205 | point your browser a t | |
| 206 | <a href="h ttp://loca lhost:8080 /examples/ jsp/securi ty/protect ed/">http: //localhos t:8080/exa mples/jsp/ security/p rotected/< /a> | |
| 207 | and log on with one of the use rnames and passwords described for the d efault | |
| 208 | <a href="# UserDataba seRealm">U serDatabas eRealm</a> .</p> | |
| 209 | ||
| 210 | </blockquo te></td></ tr></table > | |
| 211 | ||
| 212 | ||
| 213 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="M anager App lication"> <!--()-->< /a><a name ="Manager_ Applicatio n"><strong >Manager A pplication </strong>< /a></font> </td></tr> <tr><td><b lockquote> | |
| 214 | ||
| 215 | <p>If you wish to us e the <a h ref="manag er-howto.h tml">Manag er Applica tion</a> | |
| 216 | to deploy and undepl oy applica tions in a running T omcat inst allation, you | |
| 217 | MUST add t he "manage r-gui" rol e to at le ast one us ername in your selec ted | |
| 218 | Realm impl ementation . This is because t he manager web appli cation its elf uses a | |
| 219 | security c onstraint that requi res role " manager-gu i" to acce ss ANY req uest URI | |
| 220 | within the HTML inte rface of t hat applic ation.</p> | |
| 221 | ||
| 222 | <p>For sec urity reas ons, no us ername in the defaul t Realm (i .e. using | |
| 223 | <code>conf /tomcat-us ers.xml</c ode> is as signed the "manager- gui" role. | |
| 224 | Therefore, no one wi ll be able to utiliz e the feat ures of th is applica tion | |
| 225 | until the Tomcat adm inistrator specifica lly assign s this rol e to one o r more | |
| 226 | users.</p> | |
| 227 | ||
| 228 | </blockquo te></td></ tr></table > | |
| 229 | ||
| 230 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="R ealm Loggi ng"><!--() --></a><a name="Real m_Logging" ><strong>R ealm Loggi ng</strong ></a></fon t></td></t r><tr><td> <blockquot e> | |
| 231 | ||
| 232 | <p>Debuggi ng and exc eption mes sages logg ed by a <c ode>Realm< /code> wil l | |
| 233 | be reco rded by th e logging configurat ion associ ated with the contai ner | |
| 234 | for the realm: it s surround ing <a hre f="config/ context.ht ml">Contex t</a>, | |
| 235 | <a href ="config/h ost.html"> Host</a>, or | |
| 236 | <a href ="config/e ngine.html ">Engine</ a>.</p> | |
| 237 | ||
| 238 | </blockquo te></td></ tr></table > | |
| 239 | ||
| 240 | </blockquo te></td></ tr></table ><table bo rder="0" c ellspacing ="0" cellp adding="2" ><tr><td b gcolor="#5 25D76"><fo nt color=" #ffffff" f ace="arial ,helvetica .sanserif" ><a name=" Standard R ealm Imple mentations "><!--()-- ></a><a na me="Standa rd_Realm_I mplementat ions"><str ong>Standa rd Realm I mplementat ions</stro ng></a></f ont></td>< /tr><tr><t d><blockqu ote> | |
| 241 | ||
| 242 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="J DBCRealm"> <strong>JD BCRealm</s trong></a> </font></t d></tr><tr ><td><bloc kquote> | |
| 243 | ||
| 244 | <h3>Introd uction</h3 > | |
| 245 | ||
| 246 | <p><strong >JDBCRealm </strong> is an impl ementation of the To mcat 6 | |
| 247 | <code>Real m</code> i nterface t hat looks up users i n a relati onal datab ase | |
| 248 | accessed v ia a JDBC driver. T here is su bstantial configurat ion flexib ility | |
| 249 | that lets you adapt to existin g table an d column n ames, as l ong as you r | |
| 250 | database s tructure c onforms to the follo wing requi rements:</ p> | |
| 251 | <ul> | |
| 252 | <li>There must be a table, ref erenced be low as the <em>users </em> tabl e, | |
| 253 | that c ontains on e row for every vali d user tha t this <co de>Realm</ code> | |
| 254 | should recognize .</li> | |
| 255 | <li>The <e m>users</e m> table m ust contai n at least two colum ns (it may | |
| 256 | contai n more if your exist ing applic ations req uired it): | |
| 257 | <ul> | |
| 258 | <li>Us ername to be recogni zed by Tom cat when t he user lo gs in.</li > | |
| 259 | <li>Pa ssword to be recogni zed by Tom cat when t he user lo gs in. | |
| 260 | Th is value m ay in clea rtext or d igested - see below for more | |
| 261 | in formation. </li> | |
| 262 | </ul>< /li> | |
| 263 | <li>There must be a table, ref erenced be low as the <em>user roles</em> table, | |
| 264 | that c ontains on e row for every vali d role tha t is assig ned to a | |
| 265 | partic ular user. It is le gal for a user to ha ve zero, o ne, or mor e than | |
| 266 | one va lid role.< /li> | |
| 267 | <li>The <e m>user rol es</em> ta ble must c ontain at least two columns (i t may | |
| 268 | contai n more if your exist ing applic ations req uired it): | |
| 269 | <ul> | |
| 270 | <li>Us ername to be recogni zed by Tom cat (same value as i s specifie d | |
| 271 | in the <em>u sers</em> table).</l i> | |
| 272 | <li>Ro le name of a valid r ole associ ated with this user. </li> | |
| 273 | </ul>< /li> | |
| 274 | </ul> | |
| 275 | ||
| 276 | <h3>Quick Start</h3> | |
| 277 | ||
| 278 | <p>To set up Tomcat to use JDB CRealm, yo u will nee d to follo w these st eps:</p> | |
| 279 | <ol> | |
| 280 | <li>If you have not yet done s o, create tables and columns i n your dat abase | |
| 281 | that c onform to the requir ements des cribed abo ve.</li> | |
| 282 | <li>Config ure a data base usern ame and pa ssword for use by To mcat, that has | |
| 283 | at lea st read on ly access to the tab les descri bed above. (Tomcat will | |
| 284 | never attempt to write to these tabl es.)</li> | |
| 285 | <li>Place a copy of the JDBC d river you will be us ing inside the | |
| 286 | <code> $CATALINA_ HOME/lib</ code> dire ctory. | |
| 287 | Note t hat <stron g>only</st rong> JAR files are recognized !</li> | |
| 288 | <li>Set up a <code>& lt;Realm&g t;</code> element, a s describe d below, i n your | |
| 289 | <code> $CATALINA_ BASE/conf/ server.xml </code> fi le.</li> | |
| 290 | <li>Restar t Tomcat 6 if it is already ru nning.</li > | |
| 291 | </ol> | |
| 292 | ||
| 293 | <h3>Realm Element At tributes</ h3> | |
| 294 | ||
| 295 | <p>To conf igure JDBC Realm, you will crea te a <code ><Realm ></code > | |
| 296 | element an d nest it in your <c ode>$CATAL INA_BASE/c onf/server .xml</code > file, | |
| 297 | as describ ed <a href ="#Configu ring a Rea lm">above< /a>. The a ttributes for the | |
| 298 | JDBCRealm are define d in the < a href="co nfig/realm .html">Rea lm</a> con figuration | |
| 299 | documentat ion.</p> | |
| 300 | ||
| 301 | <h3>Exampl e</h3> | |
| 302 | ||
| 303 | <p>An exam ple SQL sc ript to cr eate the n eeded tabl es might l ook someth ing | |
| 304 | like this (adapt the syntax as required for your p articular database): </p> | |
| 305 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 306 | create tab le users ( | |
| 307 | user_nam e varchar(15 ) not null primary k ey, | |
| 308 | user_pas s varchar(15 ) not null | |
| 309 | ); | |
| 310 | ||
| 311 | create tab le user_ro les ( | |
| 312 | user_nam e varchar(15 ) not null , | |
| 313 | role_nam e varchar(15 ) not null , | |
| 314 | primary key (user_ name, role _name) | |
| 315 | ); | |
| 316 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 317 | ||
| 318 | <p>Example <code>Rea lm</code> elements a re include d (comment ed out) in the | |
| 319 | default <c ode>$CATAL INA_BASE/c onf/server .xml</code > file. H ere's an e xample | |
| 320 | for using a MySQL da tabase cal led "autho rity", con figured wi th the tab les | |
| 321 | described above, and accessed with usern ame "dbuse r" and pas sword "dbp ass":</p> | |
| 322 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 323 | <Realm className= "org.apach e.catalina .realm.JDB CRealm" | |
| 324 | driv erName="or g.gjt.mm.m ysql.Drive r" | |
| 325 | connect ionURL="jd bc:mysql:/ /localhost /authority ?user=dbus er&amp ;password= dbpass" | |
| 326 | use rTable="us ers" userN ameCol="us er_name" u serCredCol ="user_pas s" | |
| 327 | userRol eTable="us er_roles" roleNameCo l="role_na me"/> | |
| 328 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 329 | ||
| 330 | <h3>Additi onal Notes </h3> | |
| 331 | ||
| 332 | <p>JDBCRea lm operate s accordin g to the f ollowing r ules:</p> | |
| 333 | <ul> | |
| 334 | <li>When a user atte mpts to ac cess a pro tected res ource for the first time, | |
| 335 | Tomcat 6 will ca ll the <co de>authent icate()</c ode> metho d of this | |
| 336 | <code> Realm</cod e>. Thus, any chang es you hav e made to the databa se | |
| 337 | direct ly (new us ers, chang ed passwor ds or role s, etc.) w ill be imm ediately | |
| 338 | reflec ted.</li> | |
| 339 | <li>Once a user has been authe nticated, the user ( and his or her assoc iated | |
| 340 | roles) are cache d within T omcat for the durati on of the user's log in. | |
| 341 | (For F ORM-based authentica tion, that means unt il the ses sion times out or | |
| 342 | is inv alidated; for BASIC authentica tion, that means unt il the use r | |
| 343 | closes their bro wser). Th e cached u ser is <st rong>not</ strong> sa ved and | |
| 344 | restor ed across sessions s erialisati ons. Any c hanges to the databa se | |
| 345 | inform ation for an already authentic ated user will <stro ng>not</st rong> be | |
| 346 | reflec ted until the next t ime that u ser logs o n again.</ li> | |
| 347 | <li>Admini stering th e informat ion in the <em>users </em> and <em>user r oles</em> | |
| 348 | table is the res ponsibilit y of your own applic ations. T omcat does not | |
| 349 | provid e any buil t-in capab ilities to maintain users and roles.</li > | |
| 350 | </ul> | |
| 351 | ||
| 352 | </blockquo te></td></ tr></table > | |
| 353 | ||
| 354 | ||
| 355 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="D ataSourceR ealm"><str ong>DataSo urceRealm< /strong></ a></font>< /td></tr>< tr><td><bl ockquote> | |
| 356 | ||
| 357 | <h3>Introd uction</h3 > | |
| 358 | ||
| 359 | <p><strong >DataSourc eRealm</st rong> is a n implemen tation of the Tomcat 6 | |
| 360 | <code>Real m</code> i nterface t hat looks up users i n a relati onal datab ase | |
| 361 | accessed v ia a JNDI named JDBC DataSourc e. There is substan tial confi guration | |
| 362 | flexibilit y that let s you adap t to exist ing table and column names, as long | |
| 363 | as your da tabase str ucture con forms to t he followi ng require ments:</p> | |
| 364 | <ul> | |
| 365 | <li>There must be a table, ref erenced be low as the <em>users </em> tabl e, | |
| 366 | that c ontains on e row for every vali d user tha t this <co de>Realm</ code> | |
| 367 | should recognize .</li> | |
| 368 | <li>The <e m>users</e m> table m ust contai n at least two colum ns (it may | |
| 369 | contai n more if your exist ing applic ations req uired it): | |
| 370 | <ul> | |
| 371 | <li>Us ername to be recogni zed by Tom cat when t he user lo gs in.</li > | |
| 372 | <li>Pa ssword to be recogni zed by Tom cat when t he user lo gs in. | |
| 373 | Th is value m ay in clea rtext or d igested - see below for more | |
| 374 | in formation. </li> | |
| 375 | </ul>< /li> | |
| 376 | <li>There must be a table, ref erenced be low as the <em>user roles</em> table, | |
| 377 | that c ontains on e row for every vali d role tha t is assig ned to a | |
| 378 | partic ular user. It is le gal for a user to ha ve zero, o ne, or mor e than | |
| 379 | one va lid role.< /li> | |
| 380 | <li>The <e m>user rol es</em> ta ble must c ontain at least two columns (i t may | |
| 381 | contai n more if your exist ing applic ations req uired it): | |
| 382 | <ul> | |
| 383 | <li>Us ername to be recogni zed by Tom cat (same value as i s specifie d | |
| 384 | in the <em>u sers</em> table).</l i> | |
| 385 | <li>Ro le name of a valid r ole associ ated with this user. </li> | |
| 386 | </ul>< /li> | |
| 387 | </ul> | |
| 388 | ||
| 389 | <h3>Quick Start</h3> | |
| 390 | ||
| 391 | <p>To set up Tomcat to use Dat aSourceRea lm, you wi ll need to follow th ese steps: </p> | |
| 392 | <ol> | |
| 393 | <li>If you have not yet done s o, create tables and columns i n your dat abase | |
| 394 | that c onform to the requir ements des cribed abo ve.</li> | |
| 395 | <li>Config ure a data base usern ame and pa ssword for use by To mcat, that has | |
| 396 | at lea st read on ly access to the tab les descri bed above. (Tomcat will | |
| 397 | never attempt to write to these tabl es.)</li> | |
| 398 | <li>Config ure a JNDI named JDB C DataSour ce for you r database . Refer t o the | |
| 399 | <a hre f="jndi-da tasource-e xamples-ho wto.html"> JNDI DataS ource Exam ple HOW-TO </a> | |
| 400 | for in formation on how to configure a JNDI nam ed JDBC Da taSource.< /li> | |
| 401 | <li>Set up a <code>& lt;Realm&g t;</code> element, a s describe d below, i n your | |
| 402 | <code> $CATALINA_ BASE/conf/ server.xml </code> fi le.</li> | |
| 403 | <li>Restar t Tomcat 6 if it is already ru nning.</li > | |
| 404 | </ol> | |
| 405 | ||
| 406 | <h3>Realm Element At tributes</ h3> | |
| 407 | ||
| 408 | <p>To conf igure Data SourceReal m, you wil l create a <code>< ;Realm> </code> | |
| 409 | element an d nest it in your <c ode>$CATAL INA_BASE/c onf/server .xml</code > file, | |
| 410 | as describ ed <a href ="#Configu ring a Rea lm">above< /a>. The a ttributes for the | |
| 411 | DataSource Realm are defined in the <a hr ef="config /realm.htm l">Realm</ a> | |
| 412 | configurat ion docume ntation.</ p> | |
| 413 | ||
| 414 | <h3>Exampl e</h3> | |
| 415 | ||
| 416 | <p>An exam ple SQL sc ript to cr eate the n eeded tabl es might l ook someth ing | |
| 417 | like this (adapt the syntax as required for your p articular database): </p> | |
| 418 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 419 | create tab le users ( | |
| 420 | user_nam e varchar(15 ) not null primary k ey, | |
| 421 | user_pas s varchar(15 ) not null | |
| 422 | ); | |
| 423 | ||
| 424 | create tab le user_ro les ( | |
| 425 | user_nam e varchar(15 ) not null , | |
| 426 | role_nam e varchar(15 ) not null , | |
| 427 | primary key (user_ name, role _name) | |
| 428 | ); | |
| 429 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 430 | ||
| 431 | <p>Here is an exampl e for usin g a MySQL database c alled "aut hority", c onfigured | |
| 432 | with the t ables desc ribed abov e, and acc essed with the JNDI JDBC DataS ource with | |
| 433 | name "java :/comp/env /jdbc/auth ority".</p > | |
| 434 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 435 | <Realm className= "org.apach e.catalina .realm.Dat aSourceRea lm" | |
| 436 | dataSou rceName="j dbc/author ity" | |
| 437 | userTab le="users" userNameC ol="user_n ame" userC redCol="us er_pass" | |
| 438 | userRol eTable="us er_roles" roleNameCo l="role_na me"/> | |
| 439 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 440 | ||
| 441 | <h3>Additi onal Notes </h3> | |
| 442 | ||
| 443 | <p>DataSou rceRealm o perates ac cording to the follo wing rules :</p> | |
| 444 | <ul> | |
| 445 | <li>When a user atte mpts to ac cess a pro tected res ource for the first time, | |
| 446 | Tomcat 6 will ca ll the <co de>authent icate()</c ode> metho d of this | |
| 447 | <code> Realm</cod e>. Thus, any chang es you hav e made to the databa se | |
| 448 | direct ly (new us ers, chang ed passwor ds or role s, etc.) w ill be imm ediately | |
| 449 | reflec ted.</li> | |
| 450 | <li>Once a user has been authe nticated, the user ( and his or her assoc iated | |
| 451 | roles) are cache d within T omcat for the durati on of the user's log in. | |
| 452 | (For F ORM-based authentica tion, that means unt il the ses sion times out or | |
| 453 | is inv alidated; for BASIC authentica tion, that means unt il the use r | |
| 454 | closes their bro wser). Th e cached u ser is <st rong>not</ strong> sa ved and | |
| 455 | restor ed across sessions s erialisati ons. Any c hanges to the databa se | |
| 456 | inform ation for an already authentic ated user will <stro ng>not</st rong> be | |
| 457 | reflec ted until the next t ime that u ser logs o n again.</ li> | |
| 458 | <li>Admini stering th e informat ion in the <em>users </em> and <em>user r oles</em> | |
| 459 | table is the res ponsibilit y of your own applic ations. T omcat does not | |
| 460 | provid e any buil t-in capab ilities to maintain users and roles.</li > | |
| 461 | </ul> | |
| 462 | ||
| 463 | </blockquo te></td></ tr></table > | |
| 464 | ||
| 465 | ||
| 466 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="J NDIRealm"> <strong>JN DIRealm</s trong></a> </font></t d></tr><tr ><td><bloc kquote> | |
| 467 | ||
| 468 | <h3>Introd uction</h3 > | |
| 469 | ||
| 470 | <p><strong >JNDIRealm </strong> is an impl ementation of the To mcat 6 | |
| 471 | <code>Real m</code> i nterface t hat looks up users i n an LDAP directory | |
| 472 | server acc essed by a JNDI prov ider (typi cally, the standard LDAP | |
| 473 | provider t hat is ava ilable wit h the JNDI API class es). The r ealm | |
| 474 | supports a variety o f approach es to usin g a direct ory for | |
| 475 | authentica tion.</p> | |
| 476 | ||
| 477 | <h4>Connec ting to th e director y</h4> | |
| 478 | ||
| 479 | <p>The rea lm's conne ction to t he directo ry is defi ned by the | |
| 480 | <strong>co nnectionUR L</strong> configura tion attri bute. This is a URL | |
| 481 | whose form at is defi ned by the JNDI prov ider. It i s usually an LDAP | |
| 482 | URL that s pecifies t he domain name of th e director y server t o connect | |
| 483 | to, and op tionally t he port nu mber and d istinguish ed name (D N) of the | |
| 484 | required r oot naming context.< /p> | |
| 485 | ||
| 486 | <p>If you have more than one p rovider yo u can conf igure an | |
| 487 | <strong>al ternateURL </strong>. If a soc ket connec tion can n ot be | |
| 488 | made to th e provider at the <s trong>conn ectionURL< /strong> a n | |
| 489 | attempt wi ll be made to use th e <strong> alternateU RL</strong >.</p> | |
| 490 | ||
| 491 | <p>When ma king a con nection in order to search the directory and | |
| 492 | retrieve u ser and ro le informa tion, the realm auth enticates itself to | |
| 493 | the direct ory with t he usernam e and pass word speci fied by th e | |
| 494 | <strong>co nnectionNa me</strong > and | |
| 495 | <strong>co nnectionPa ssword</st rong> prop erties. If these pro perties | |
| 496 | are not sp ecified th e connecti on is anon ymous. Thi s is suffi cient in | |
| 497 | many cases . | |
| 498 | </p> | |
| 499 | ||
| 500 | ||
| 501 | <h4>Select ing the us er's direc tory entry </h4> | |
| 502 | ||
| 503 | <p>Each us er that ca n be authe nticated m ust be rep resented i n the | |
| 504 | directory by an indi vidual ent ry that co rresponds to an elem ent in the | |
| 505 | initial <c ode>DirCon text</code > defined by the | |
| 506 | <strong>co nnectionUR L</strong> attribute . This use r entry mu st have an | |
| 507 | attribute containing the usern ame that i s presente d for | |
| 508 | authentica tion.</p> | |
| 509 | ||
| 510 | <p>Often t he disting uished nam e of the u ser's entr y contains the | |
| 511 | username p resented f or authent ication bu t is other wise the s ame for | |
| 512 | all users. In this c ase the <s trong>user Pattern</s trong> att ribute may | |
| 513 | be used to specify t he DN, wit h "{0}" ma rking wher e | |
| 514 | the userna me should be substit uted.</p> | |
| 515 | ||
| 516 | <p>Otherwi se the rea lm must se arch the d irectory t o find a u nique entr y | |
| 517 | containing the usern ame. The f ollowing a ttributes configure this | |
| 518 | search: | |
| 519 | ||
| 520 | <ul> | |
| 521 | <li>< strong>use rBase</str ong> - the entry tha t is the b ase of | |
| 522 | t he subtree containin g users. If not spe cified, th e search | |
| 523 | b ase is the top-level context.< /li> | |
| 524 | ||
| 525 | <li>< strong>use rSubtree</ strong> - the search scope. Se t to | |
| 526 | < code>true< /code> if you wish t o search t he entire subtree | |
| 527 | r ooted at t he <strong >userBase< /strong> e ntry. The default va lue | |
| 528 | o f <code>fa lse</code> requests a single-l evel searc h | |
| 529 | i ncluding o nly the to p level.</ li> | |
| 530 | ||
| 531 | <li>< strong>use rSearch</s trong> - p attern spe cifying th e LDAP | |
| 532 | s earch filt er to use after subs titution o f the user name.</li> | |
| 533 | ||
| 534 | </ul> | |
| 535 | </p> | |
| 536 | ||
| 537 | ||
| 538 | <h4>Authen ticating t he user</h 4> | |
| 539 | ||
| 540 | <ul> | |
| 541 | <li> | |
| 542 | <p><b>Bind mode</b>< /p> | |
| 543 | ||
| 544 | <p>By defa ult the re alm authen ticates a user by bi nding to | |
| 545 | the direct ory with t he DN of t he entry f or that us er and the password | |
| 546 | presented by the use r. If this simple bi nd succeed s the user is consid ered to | |
| 547 | be authent icated.</p > | |
| 548 | ||
| 549 | <p>For sec urity reas ons a dire ctory may store a di gest of th e user's | |
| 550 | password r ather than the clear text vers ion (see < a href="#D igested Pa sswords">D igested Pa sswords</a > for more informati on). In th at case, | |
| 551 | as part of the simpl e bind ope ration the directory automatic ally | |
| 552 | computes t he correct digest of the plain text passw ord presen ted by the | |
| 553 | user befor e validati ng it agai nst the st ored value . In bind mode, | |
| 554 | therefore, the realm is not in volved in digest pro cessing. T he | |
| 555 | <strong>di gest</stro ng> attrib ute is not used, and will be i gnored if | |
| 556 | set.</p> | |
| 557 | </li> | |
| 558 | ||
| 559 | <li> | |
| 560 | <p><b>Comp arison mod e</b></p> | |
| 561 | <p>Alterna tively, th e realm ma y retrieve the store d | |
| 562 | password f rom the di rectory an d compare it explici tly with t he value | |
| 563 | presented by the use r. This mo de is conf igured by setting th e | |
| 564 | <strong>us erPassword </strong> attribute to the nam e of a dir ectory | |
| 565 | attribute in the use r's entry that conta ins the pa ssword.</p > | |
| 566 | ||
| 567 | <p>Compari son mode h as some di sadvantage s. First, the | |
| 568 | <strong>co nnectionNa me</strong > and | |
| 569 | <strong>co nnectionPa ssword</st rong> attr ibutes mus t be confi gured to | |
| 570 | allow the realm to r ead users' passwords in the di rectory. F or | |
| 571 | security r easons thi s is gener ally undes irable; in deed many directory | |
| 572 | implementa tions will not allow even the directory manager to read | |
| 573 | these pass words. In addition, the realm must handl e password digests | |
| 574 | itself, in cluding va riations i n the algo rithms use d and ways of | |
| 575 | representi ng passwor d hashes i n the dire ctory. How ever, the realm may | |
| 576 | sometimes need acces s to the s tored pass word, for example to support | |
| 577 | HTTP Diges t Access A uthenticat ion (RFC 2 069). (Not e that HTT P digest | |
| 578 | authentica tion is di fferent fr om the sto rage of pa ssword dig ests in | |
| 579 | the reposi tory for u ser inform ation as d iscussed a bove). | |
| 580 | </p> | |
| 581 | </li> | |
| 582 | </ul> | |
| 583 | ||
| 584 | <h4>Assign ing roles to the use r</h4> | |
| 585 | ||
| 586 | <p>The dir ectory rea lm support s two appr oaches to the repres entation | |
| 587 | of roles i n the dire ctory:</p> | |
| 588 | ||
| 589 | <ul> | |
| 590 | <li> | |
| 591 | <p><b>Role s as expli cit direct ory entrie s</b></p> | |
| 592 | ||
| 593 | <p>Roles m ay be repr esented by explicit directory entries. A role | |
| 594 | entry is u sually an LDAP group entry wit h one attr ibute | |
| 595 | containing the name of the rol e and anot her whose values are the | |
| 596 | distinguis hed names or usernam es of the users in t hat role. The | |
| 597 | following attributes configure a directo ry search to | |
| 598 | find the n ames of ro les associ ated with the authen ticated us er:</p> | |
| 599 | ||
| 600 | <ul> | |
| 601 | <li><stron g>roleBase </strong> - the base entry for the role search. | |
| 602 | If not specified , the sear ch base is the top-l evel direc tory | |
| 603 | contex t.</li> | |
| 604 | ||
| 605 | <li><stron g>roleSubt ree</stron g> - the s earch | |
| 606 | scope. Set to <c ode>true</ code> if y ou wish to search th e entire | |
| 607 | subtre e rooted a t the <cod e>roleBase </code> en try. The d efault | |
| 608 | value of <code>f alse</code > requests a single- level sear ch | |
| 609 | includ ing the to p level on ly.</li> | |
| 610 | ||
| 611 | <li><stron g>roleSear ch</strong > - the LD AP search filter for | |
| 612 | select ing role e ntries. It optionall y includes pattern | |
| 613 | replac ements "{0 }" for the distingui shed name and/or "{1 }" for the | |
| 614 | userna me of the authentica ted user.< /li> | |
| 615 | ||
| 616 | <li><stron g>roleName </strong> - the attr ibute in a role entr y | |
| 617 | conta ining the name of th at role.</ li> | |
| 618 | ||
| 619 | <li><stron g>roleNest ed</strong > - enable nested ro les. Set t o | |
| 620 | <code >true</cod e> if you want to ne st roles i n roles. I f configur ed | |
| 621 | every newly fou nd roleNam e and dist inguished | |
| 622 | Name will be re cursively tried for a new role search. | |
| 623 | The d efault val ue is <cod e>false</c ode>.</li> | |
| 624 | ||
| 625 | </ul> | |
| 626 | ||
| 627 | </li> | |
| 628 | </ul> | |
| 629 | ||
| 630 | <ul> | |
| 631 | <li> | |
| 632 | <p><b>Role s as an at tribute of the user entry</b>< /p> | |
| 633 | ||
| 634 | <p>Role na mes may al so be held as the va lues of an attribute in the | |
| 635 | user's dir ectory ent ry. Use <s trong>user RoleName</ strong> to specify | |
| 636 | the name o f this att ribute.</p > | |
| 637 | ||
| 638 | </li> | |
| 639 | </ul> | |
| 640 | <p>A combi nation of both appro aches to r ole repres entation m ay be used .</p> | |
| 641 | ||
| 642 | <h3>Quick Start</h3> | |
| 643 | ||
| 644 | <p>To set up Tomcat to use JND IRealm, yo u will nee d to follo w these st eps:</p> | |
| 645 | <ol> | |
| 646 | <li>Make s ure your d irectory s erver is c onfigured with a sch ema that m atches | |
| 647 | the re quirements listed ab ove.</li> | |
| 648 | <li>If req uired, con figure a u sername an d password for use b y Tomcat, that has | |
| 649 | read o nly access to the in formation described above. (T omcat will | |
| 650 | never attempt to modify th is informa tion.)</li > | |
| 651 | <li>Set up a <code>& lt;Realm&g t;</code> element, a s describe d below, i n your | |
| 652 | <code> $CATALINA_ BASE/conf/ server.xml </code> fi le.</li> | |
| 653 | <li>Restar t Tomcat 6 if it is already ru nning.</li > | |
| 654 | </ol> | |
| 655 | ||
| 656 | <h3>Realm Element At tributes</ h3> | |
| 657 | ||
| 658 | <p>To conf igure JNDI Realm, you will crea te a <code ><Realm ></code > | |
| 659 | element an d nest it in your <c ode>$CATAL INA_BASE/c onf/server .xml</code > file, | |
| 660 | as describ ed <a href ="#Configu ring a Rea lm">above< /a>. The a ttributes for the | |
| 661 | JNDIRealm are define d in the < a href="co nfig/realm .html">Rea lm</a> con figuration | |
| 662 | documentat ion.</p> | |
| 663 | ||
| 664 | <h3>Exampl e</h3> | |
| 665 | ||
| 666 | <p>Creatio n of the a ppropriate schema in your dire ctory serv er is beyo nd the | |
| 667 | scope of t his docume nt, becaus e it is un ique to ea ch directo ry server | |
| 668 | implementa tion. In the exampl es below, we will as sume that you are us ing a | |
| 669 | distributi on of the OpenLDAP d irectory s erver (ver sion 2.0.1 1 or later ), which | |
| 670 | can be dow nloaded fr om | |
| 671 | <a href="h ttp://www. openldap.o rg">http:/ /www.openl dap.org</a >. Assume that | |
| 672 | your <code >slapd.con f</code> f ile contai ns the fol lowing set tings | |
| 673 | (among oth ers):</p> | |
| 674 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 675 | database l dbm | |
| 676 | suffix dc= "mycompany ",dc="com" | |
| 677 | rootdn "cn =Manager,d c=mycompan y,dc=com" | |
| 678 | rootpw PW | |
| 679 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 680 | ||
| 681 | <p>We will assume fo r <code>co nnectionUR L</code> t hat the di rectory | |
| 682 | server run s on the s ame machin e as Tomca t. See <a href="htt p://java.s un.com/pro ducts/jndi /docs.html ">http://j ava.sun.co m/products /jndi/docs .html</a> | |
| 683 | for more i nformation about con figuring a nd using t he JNDI LD AP | |
| 684 | provider.< /p> | |
| 685 | ||
| 686 | <p>Next, a ssume that this dire ctory serv er has bee n populate d with ele ments | |
| 687 | as shown b elow (in L DIF format ):</p> | |
| 688 | ||
| 689 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 690 | ||
| 691 | # Define t op-level e ntry | |
| 692 | dn: dc=myc ompany,dc= com | |
| 693 | objectClas s: dcObjec t | |
| 694 | dc:mycompa ny | |
| 695 | ||
| 696 | # Define a n entry to contain p eople | |
| 697 | # searches for users are based on this e ntry | |
| 698 | dn: ou=peo ple,dc=myc ompany,dc= com | |
| 699 | objectClas s: organiz ationalUni t | |
| 700 | ou: people | |
| 701 | ||
| 702 | # Define a user entr y for Jane t Jones | |
| 703 | dn: uid=jj ones,ou=pe ople,dc=my company,dc =com | |
| 704 | objectClas s: inetOrg Person | |
| 705 | uid: jjone s | |
| 706 | sn: jones | |
| 707 | cn: janet jones | |
| 708 | mail: j.jo nes@mycomp any.com | |
| 709 | userPasswo rd: janet | |
| 710 | ||
| 711 | # Define a user entr y for Fred Bloggs | |
| 712 | dn: uid=fb loggs,ou=p eople,dc=m ycompany,d c=com | |
| 713 | objectClas s: inetOrg Person | |
| 714 | uid: fblog gs | |
| 715 | sn: bloggs | |
| 716 | cn: fred b loggs | |
| 717 | mail: f.bl oggs@mycom pany.com | |
| 718 | userPasswo rd: fred | |
| 719 | ||
| 720 | # Define a n entry to contain L DAP groups | |
| 721 | # searches for roles are based on this e ntry | |
| 722 | dn: ou=gro ups,dc=myc ompany,dc= com | |
| 723 | objectClas s: organiz ationalUni t | |
| 724 | ou: groups | |
| 725 | ||
| 726 | # Define a n entry fo r the "tom cat" role | |
| 727 | dn: cn=tom cat,ou=gro ups,dc=myc ompany,dc= com | |
| 728 | objectClas s: groupOf UniqueName s | |
| 729 | cn: tomcat | |
| 730 | uniqueMemb er: uid=jj ones,ou=pe ople,dc=my company,dc =com | |
| 731 | uniqueMemb er: uid=fb loggs,ou=p eople,dc=m ycompany,d c=com | |
| 732 | ||
| 733 | # Define a n entry fo r the "rol e1" role | |
| 734 | dn: cn=rol e1,ou=grou ps,dc=myco mpany,dc=c om | |
| 735 | objectClas s: groupOf UniqueName s | |
| 736 | cn: role1 | |
| 737 | uniqueMemb er: uid=fb loggs,ou=p eople,dc=m ycompany,d c=com | |
| 738 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 739 | ||
| 740 | <p>An exam ple <code> Realm</cod e> element for the O penLDAP di rectory | |
| 741 | server con figured as described above mig ht look li ke this, a ssuming | |
| 742 | that users use their uid (e.g. jjones) t o login to the | |
| 743 | applicatio n and that an anonym ous connec tion is su fficient t o search | |
| 744 | the direct ory and re trieve rol e informat ion:</p> | |
| 745 | ||
| 746 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 747 | <Realm classNam e="org.apa che.catali na.realm.J NDIRealm" | |
| 748 | conne ctionURL=" ldap://loc alhost:389 " | |
| 749 | use rPattern=" uid={0},ou =people,dc =mycompany ,dc=com" | |
| 750 | roleBase=" ou=groups, dc=mycompa ny,dc=com" | |
| 751 | roleName=" cn" | |
| 752 | ro leSearch=" (uniqueMem ber={0})" | |
| 753 | /> | |
| 754 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 755 | ||
| 756 | <p>With th is configu ration, th e realm wi ll determi ne the use r's | |
| 757 | distinguis hed name b y substitu ting the u sername in to the | |
| 758 | <code>user Pattern</c ode>, auth enticate b y binding to the dir ectory | |
| 759 | with this DN and the password received f rom the us er, and se arch the | |
| 760 | directory to find th e user's r oles.</p> | |
| 761 | ||
| 762 | <p>Now sup pose that users are expected t o enter th eir email address | |
| 763 | rather tha n their us erid when logging in . In this case the r ealm must | |
| 764 | search the directory for the u ser's entr y. (A sear ch is also necessary | |
| 765 | when user entries ar e held in multiple s ubtrees co rrespondin g perhaps | |
| 766 | to differe nt organiz ational un its or com pany locat ions).</p> | |
| 767 | ||
| 768 | <p>Further , suppose that in ad dition to the group entries yo u want to | |
| 769 | use an att ribute of the user's entry to hold roles . Now the entry for | |
| 770 | Janet Jone s might re ad as foll ows:</p> | |
| 771 | ||
| 772 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 773 | dn: uid=jj ones,ou=pe ople,dc=my company,dc =com | |
| 774 | objectClas s: inetOrg Person | |
| 775 | uid: jjone s | |
| 776 | sn: jones | |
| 777 | cn: janet jones | |
| 778 | mail: j.jo nes@mycomp any.com | |
| 779 | memberOf: role2 | |
| 780 | memberOf: role3 | |
| 781 | userPasswo rd: janet | |
| 782 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 783 | ||
| 784 | <p> This r ealm confi guration w ould satis fy the new requireme nts:</p> | |
| 785 | ||
| 786 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 787 | <Realm classNam e="org.apa che.catali na.realm.J NDIRealm" | |
| 788 | conne ctionURL=" ldap://loc alhost:389 " | |
| 789 | userBase=" ou=people, dc=mycompa ny,dc=com" | |
| 790 | us erSearch=" (mail={0}) " | |
| 791 | user RoleName=" memberOf" | |
| 792 | roleBase=" ou=groups, dc=mycompa ny,dc=com" | |
| 793 | roleName=" cn" | |
| 794 | ro leSearch=" (uniqueMem ber={0})" | |
| 795 | /> | |
| 796 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 797 | ||
| 798 | <p>Now whe n Janet Jo nes logs i n as "j.jo nes@mycomp any.com", the realm | |
| 799 | searches t he directo ry for a u nique entr y with tha t value as its mail | |
| 800 | attribute and attemp ts to bind to the di rectory as | |
| 801 | <code>uid= jjones,ou= people,dc= mycompany, dc=com</co de> with t he given | |
| 802 | password. If authent ication su cceeds, sh e is assig ned three roles: | |
| 803 | "role2" an d "role3", the value s of the " memberOf" attribute in her | |
| 804 | directory entry, and "tomcat", the value of the "c n" attribu te in the | |
| 805 | only group entry of which she is a membe r.</p> | |
| 806 | ||
| 807 | <p>Finally , to authe nticate th e user by retrieving | |
| 808 | the passwo rd from th e director y and maki ng a local compariso n in the | |
| 809 | realm, you might use a realm c onfigurati on like th is:</p> | |
| 810 | ||
| 811 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 812 | <Realm classNam e="org.apa che.catali na.realm.J NDIRealm" | |
| 813 | connec tionName=" cn=Manager ,dc=mycomp any,dc=com " | |
| 814 | connection Password=" PW " | |
| 815 | connection URL="ldap: //localhos t: PORT " | |
| 816 | user Password=" userPasswo rd" | |
| 817 | use rPattern=" uid={0},ou =people,dc =mycompany ,dc=com" | |
| 818 | roleBase=" ou=groups, dc=mycompa ny,dc=com" | |
| 819 | roleName=" cn" | |
| 820 | ro leSearch=" (uniqueMem ber={0})" | |
| 821 | /> | |
| 822 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 823 | ||
| 824 | <p>However , as discu ssed above , the defa ult bind m ode for | |
| 825 | authentica tion is us ually to b e preferre d.</p> | |
| 826 | ||
| 827 | <h3>Additi onal Notes </h3> | |
| 828 | ||
| 829 | <p>JNDIRea lm operate s accordin g to the f ollowing r ules:</p> | |
| 830 | <ul> | |
| 831 | <li>When a user atte mpts to ac cess a pro tected res ource for the first time, | |
| 832 | Tomcat 6 will ca ll the <co de>authent icate()</c ode> metho d of this | |
| 833 | <code> Realm</cod e>. Thus, any chang es you hav e made to the direct ory | |
| 834 | (new u sers, chan ged passwo rds or rol es, etc.) will be im mediately | |
| 835 | reflec ted.</li> | |
| 836 | <li>Once a user has been authe nticated, the user ( and his or her assoc iated | |
| 837 | roles) are cache d within T omcat for the durati on of the user's log in. | |
| 838 | (For F ORM-based authentica tion, that means unt il the ses sion times out or | |
| 839 | is inv alidated; for BASIC authentica tion, that means unt il the use r | |
| 840 | closes their bro wser). Th e cached u ser is <st rong>not</ strong> sa ved and | |
| 841 | restor ed across sessions s erialisati ons. Any c hanges to the direct ory | |
| 842 | inform ation for an already authentic ated user will <stro ng>not</st rong> be | |
| 843 | reflec ted until the next t ime that u ser logs o n again.</ li> | |
| 844 | <li>Admini stering th e informat ion in the directory server | |
| 845 | is the responsib ility of y our own ap plications . Tomcat does not | |
| 846 | provid e any buil t-in capab ilities to maintain users and roles.</li > | |
| 847 | </ul> | |
| 848 | ||
| 849 | </blockquo te></td></ tr></table > | |
| 850 | ||
| 851 | ||
| 852 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="U serDatabas eRealm"><s trong>User DatabaseRe alm</stron g></a></fo nt></td></ tr><tr><td ><blockquo te> | |
| 853 | ||
| 854 | <h3>Introd uction</h3 > | |
| 855 | ||
| 856 | <p><strong >UserDatab aseRealm</ strong> is an implem entation o f the Tomc at 6 | |
| 857 | <code>Real m</code> i nterface t hat uses a JNDI reso urce to st ore user | |
| 858 | informatio n. By defa ult, the J NDI resour ce is back ed by an X ML file. I t is not | |
| 859 | designed f or large-s cale produ ction use. At startu p time, th e UserData baseRealm | |
| 860 | loads info rmation ab out all us ers, and t heir corre sponding r oles, from an XML | |
| 861 | document ( by default , this doc ument is l oaded from | |
| 862 | <code>$CAT ALINA_BASE /conf/tomc at-users.x ml</code>) . The user s, their p asswords | |
| 863 | and their roles may all be edi ting dynam ically, ty pically vi a JMX. Cha nges may | |
| 864 | be saved a nd will be reflected in the XM L file.</p > | |
| 865 | ||
| 866 | <h3>Realm Element At tributes</ h3> | |
| 867 | ||
| 868 | <p>To conf igure User DatabaseRe alm, you w ill create a <code>& lt;Realm&g t;</code> | |
| 869 | element an d nest it in your <c ode>$CATAL INA_BASE/c onf/server .xml</code > file, | |
| 870 | as describ ed <a href ="#Configu ring a Rea lm">above< /a>. The a ttributes for the | |
| 871 | UserDataba seRealm ar e defined in the <a href="conf ig/realm.h tml">Realm </a> | |
| 872 | configurat ion docume ntation.</ p> | |
| 873 | ||
| 874 | <h3>User F ile Format </h3> | |
| 875 | ||
| 876 | <p>The use rs file us es the sam e format a s the | |
| 877 | <a href="# MemoryReal m">MemoryR ealm</a>.< /p> | |
| 878 | ||
| 879 | <h3>Exampl e</h3> | |
| 880 | ||
| 881 | <p>The def ault insta llation of Tomcat 6 is configu red with a UserDatab aseRealm | |
| 882 | nested ins ide the <c ode><En gine></ code> elem ent, so th at it appl ies | |
| 883 | to all vir tual hosts and web a pplication s. The de fault cont ents of th e | |
| 884 | <code>conf /tomcat-us ers.xml</c ode> file is:</p> | |
| 885 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 886 | <tomcat -users> | |
| 887 | <user name="tom cat" passw ord="tomca t" roles=" tomcat" /& gt; | |
| 888 | <user name="rol e1" passw ord="tomca t" roles=" role1" /& gt; | |
| 889 | <user name="bot h" passw ord="tomca t" roles=" tomcat,rol e1" /> | |
| 890 | </tomca t-users> ; | |
| 891 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 892 | ||
| 893 | <h3>Additi onal Notes </h3> | |
| 894 | ||
| 895 | <p>UserDat abaseRealm operates according to the fol lowing rul es:</p> | |
| 896 | <ul> | |
| 897 | <li>When T omcat firs t starts u p, it load s all defi ned users and their | |
| 898 | associ ated infor mation fro m the user s file. Ch anges made to the da ta in | |
| 899 | this f ile will < strong>not </strong> be recogni zed until Tomcat is | |
| 900 | restar ted. Chang es may be made via t he UserDat abase reso urce. Tomc at | |
| 901 | provid es MBeans that may b e accessed via JMX f or this pu rpose.</li > | |
| 902 | <li>When a user atte mpts to ac cess a pro tected res ource for the first time, | |
| 903 | Tomcat 6 will ca ll the <co de>authent icate()</c ode> metho d of this | |
| 904 | <code> Realm</cod e>.</li> | |
| 905 | <li>Once a user has been authe nticated, the user ( and his or her assoc iated | |
| 906 | roles) are cache d within T omcat for the durati on of the user's log in. | |
| 907 | (For F ORM-based authentica tion, that means unt il the ses sion times out or | |
| 908 | is inv alidated; for BASIC authentica tion, that means unt il the use r | |
| 909 | closes their bro wser). Th e cached u ser is <st rong>not</ strong> sa ved and | |
| 910 | restor ed across sessions s erialisati ons.</li> | |
| 911 | </ul> | |
| 912 | ||
| 913 | ||
| 914 | </blockquo te></td></ tr></table > | |
| 915 | ||
| 916 | ||
| 917 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="M emoryRealm "><strong> MemoryReal m</strong> </a></font ></td></tr ><tr><td>< blockquote > | |
| 918 | ||
| 919 | <h3>Introd uction</h3 > | |
| 920 | ||
| 921 | <p><strong >MemoryRea lm</strong > is a sim ple demons tration im plementati on of the | |
| 922 | Tomcat 6 < code>Realm </code> in terface. It is not designed f or product ion use. | |
| 923 | At startup time, Mem oryRealm l oads infor mation abo ut all use rs, and th eir | |
| 924 | correspond ing roles, from an X ML documen t (by defa ult, this document i s loaded | |
| 925 | from <code >$CATALINA _BASE/conf /tomcat-us ers.xml</c ode>). Ch anges to t he data | |
| 926 | in this fi le are not recognize d until To mcat is re started.</ p> | |
| 927 | ||
| 928 | <h3>Realm Element At tributes</ h3> | |
| 929 | ||
| 930 | <p>To conf igure Memo ryRealm, y ou will cr eate a <co de><Rea lm></co de> | |
| 931 | element an d nest it in your <c ode>$CATAL INA_BASE/c onf/server .xml</code > file, | |
| 932 | as describ ed <a href ="#Configu ring a Rea lm">above< /a>. The a ttributes for the | |
| 933 | MemoryReal m are defi ned in the <a href=" config/rea lm.html">R ealm</a> | |
| 934 | configurat ion docume ntation.</ p> | |
| 935 | ||
| 936 | <h3>User F ile Format </h3> | |
| 937 | ||
| 938 | <p>The use rs file (b y default, <code>con f/tomcat-u sers.xml</ code> must be an | |
| 939 | XML docume nt, with a root elem ent <code> <tomcat -users> </code>. Nested | |
| 940 | inside the root elem ent will b e a <code> <user&g t;</code> element fo r each | |
| 941 | valid user , consisti ng of the following attributes :</p> | |
| 942 | <ul> | |
| 943 | <li><stron g>name</st rong> - Us ername thi s user mus t log on w ith.</li> | |
| 944 | <li><stron g>password </strong> - Password this user must log on with (i n | |
| 945 | clear text if th e <code>di gest</code > attribut e was not set on the | |
| 946 | <code> <Realm& gt;</code> element, or digeste d appropri ately as | |
| 947 | descri bed <a hre f="#Digest ed Passwor ds">here</ a> otherwi se).</li> | |
| 948 | <li><stron g>roles</s trong> - C omma-delim ited list of the rol e names | |
| 949 | associ ated with this user. </li> | |
| 950 | </ul> | |
| 951 | ||
| 952 | <h3>Additi onal Notes </h3> | |
| 953 | ||
| 954 | <p>MemoryR ealm opera tes accord ing to the following rules:</p > | |
| 955 | <ul> | |
| 956 | <li>When T omcat firs t starts u p, it load s all defi ned users and their | |
| 957 | associ ated infor mation fro m the user s file. C hanges to the data i n | |
| 958 | this f ile will < strong>not </strong> be recogni zed until Tomcat is | |
| 959 | restar ted.</li> | |
| 960 | <li>When a user atte mpts to ac cess a pro tected res ource for the first time, | |
| 961 | Tomcat 6 will ca ll the <co de>authent icate()</c ode> metho d of this | |
| 962 | <code> Realm</cod e>.</li> | |
| 963 | <li>Once a user has been authe nticated, the user ( and his or her assoc iated | |
| 964 | roles) are cache d within T omcat for the durati on of the user's log in. | |
| 965 | (For F ORM-based authentica tion, that means unt il the ses sion times out or | |
| 966 | is inv alidated; for BASIC authentica tion, that means unt il the use r | |
| 967 | closes their bro wser). Th e cached u ser is <st rong>not</ strong> sa ved and | |
| 968 | restor ed across sessions s erialisati ons.</li> | |
| 969 | <li>Admini stering th e informat ion in the users fil e is the r esponsibil ity | |
| 970 | of you r applicat ion. Tomc at does no t | |
| 971 | provid e any buil t-in capab ilities to maintain users and roles.</li > | |
| 972 | </ul> | |
| 973 | ||
| 974 | ||
| 975 | </blockquo te></td></ tr></table > | |
| 976 | ||
| 977 | ||
| 978 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="J AASRealm"> <strong>JA ASRealm</s trong></a> </font></t d></tr><tr ><td><bloc kquote> | |
| 979 | ||
| 980 | <h3>Introd uction</h3 > | |
| 981 | ||
| 982 | <p ><strong>J AASRealm</ strong> is an implem entation o f the Tomc at | |
| 983 | 6 <code>Re alm</code> interface that auth enticates users thro ugh the Ja va | |
| 984 | Authentica tion & Authoriza tion Servi ce (JAAS) framework which is n ow | |
| 985 | provided a s part of the standa rd J2SE AP I.</p> | |
| 986 | <p >Using JAA SRealm giv es the dev eloper the ability t o combine | |
| 987 | practicall y any conc eivable se curity rea lm with To mcat's CMA . </p> | |
| 988 | <p >JAASRealm is protot ype for To mcat of th e JAAS-bas ed | |
| 989 | J2EE authe ntication framework for J2EE v 1.4, based on the <a href="htt p://www.jc p.org/en/j sr/detail? id=196">JC P Specific ation | |
| 990 | Request 19 6</a> to e nhance con tainer-man aged secur ity and pr omote | |
| 991 | 'pluggable ' authenti cation mec hanisms wh ose implem entations would be | |
| 992 | container- independen t. | |
| 993 | </ p> | |
| 994 | <p >Based on the JAAS l ogin modul e and prin cipal (see <code>jav ax.securit y.auth.spi .LoginModu le</code> | |
| 995 | and <code> javax.secu rity.Princ ipal</code >), you ca n develop your own | |
| 996 | security m echanism o r wrap ano ther third -party mec hanism for | |
| 997 | integratio n with the CMA as im plemented by Tomcat. | |
| 998 | </ p> | |
| 999 | ||
| 1000 | <h 3>Quick St art</h3> | |
| 1001 | <p >To set up Tomcat to use JAASR ealm with your own J AAS login module, | |
| 1002 | you will need to fo llow these steps:</p > | |
| 1003 | <o l> | |
| 1004 | <li>Write your own L oginModule , User and Role clas ses based | |
| 1005 | on JAAS (s ee | |
| 1006 | <a href="h ttp://docs .oracle.co m/javase/1 .4.2/docs/ guide/secu rity/jaas/ tutorials/ GeneralAcn Only.html" >the | |
| 1007 | JAAS Authe ntication Tutorial</ a> and | |
| 1008 | <a href="h ttp://docs .oracle.co m/javase/1 .4.2/docs/ guide/secu rity/jaas/ JAASLMDevG uide.html" >the JAAS Login Modu le | |
| 1009 | Developer' s Guide</a >) to be m anaged by the JAAS L ogin | |
| 1010 | Context (< code>javax .security. auth.login .LoginCont ext</code> ) | |
| 1011 | When devel oping your LoginModu le, note t hat JAASRe alm's buil t-in <code >CallbackH andler</co de> | |
| 1012 | only recog nizes the <code>Name Callback</ code> and <code>Pass wordCallba ck</code> at present . | |
| 1013 | </li> | |
| 1014 | <li>Althou gh not spe cified in JAAS, you should cre ate | |
| 1015 | seperate c lasses to distinguis h between users and roles, ext ending <co de>javax.s ecurity.Pr incipal</c ode>, | |
| 1016 | so that To mcat can t ell which Principals returned from your login | |
| 1017 | module are users and which are roles (se e <code>or g.apache.c atalina.re alm.JAASRe alm</code> ). | |
| 1018 | Regardless , the firs t Principa l returned is <em>al ways</em> treated as the user Principal. | |
| 1019 | </li> | |
| 1020 | <li>Place the compil ed classes on Tomcat 's classpa th | |
| 1021 | </li> | |
| 1022 | <li>Set up a login.c onfig file for Java (see <a hr ef="http:/ /docs.orac le.com/jav ase/1.4.2/ docs/guide /security/ jaas/tutor ials/Login ConfigFile .html">JAA S | |
| 1023 | LoginConfi g file</a> ) and tell Tomcat wh ere to fin d it by sp ecifying | |
| 1024 | its locati on to the JVM, for i nstance by setting t he environ ment | |
| 1025 | variable: <code>JAVA _OPTS=$JAV A_OPTS -Dj ava.securi ty.auth.lo gin.config ==$CATALIN A_BASE/con f/jaas.con fig</code> </li> | |
| 1026 | ||
| 1027 | <li>Config ure your s ecurity-co nstraints in your we b.xml for | |
| 1028 | the resour ces you wa nt to prot ect</li> | |
| 1029 | <li>Config ure the JA ASRealm mo dule in yo ur server. xml </li> | |
| 1030 | <li>Restar t Tomcat 6 if it is already ru nning.</li > | |
| 1031 | </ ol> | |
| 1032 | <h 3>Realm El ement Attr ibutes</h3 > | |
| 1033 | <p >To config ure JAASRe alm as for step 6 ab ove, you c reate | |
| 1034 | a <code>&l t;Realm> ;</code> e lement and nest it i n your | |
| 1035 | <code>$CAT ALINA_BASE /conf/serv er.xml</co de> | |
| 1036 | file withi n your <co de><Eng ine></c ode> node. The attri butes for the | |
| 1037 | JAASRealm are define d in the < a href="co nfig/realm .html">Rea lm</a> | |
| 1038 | configurat ion docume ntation.</ p> | |
| 1039 | ||
| 1040 | <h3>Exampl e</h3> | |
| 1041 | ||
| 1042 | <p>Here is an exampl e of how y our server .xml snipp et should look.</p> | |
| 1043 | ||
| 1044 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 1045 | <Realm className= "org.apach e.catalina .realm.JAA SRealm" | |
| 1046 | appN ame="MyFoo Realm" | |
| 1047 | userCl assNames=" org.foobar .realm.Foo User" | |
| 1048 | roleCl assNames=" org.foobar .realm.Foo Role"/> | |
| 1049 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 1050 | ||
| 1051 | <p>It is t he respons ibility of your logi n module t o create a nd save Us er and | |
| 1052 | Role objec ts represe nting Prin cipals for the user | |
| 1053 | (<code>jav ax.securit y.auth.Sub ject</code >). If you r login mo dule doesn 't | |
| 1054 | create a u ser object but also doesn't th row a logi n exceptio n, then th e | |
| 1055 | Tomcat CMA will brea k and you will be le ft at the | |
| 1056 | http://loc alhost:808 0/myapp/j_ security_c heck URI o r at some other | |
| 1057 | unspecifie d location .</p> | |
| 1058 | ||
| 1059 | <p >The flexi bility of the JAAS a pproach is two-fold: </p> | |
| 1060 | <u l> | |
| 1061 | <li>you ca n carry ou t whatever processin g you requ ire behind | |
| 1062 | the scenes in your o wn login m odule.</li > | |
| 1063 | <li>you ca n plug in a complete ly differe nt LoginMo dule by ch anging the configura tion | |
| 1064 | and restar ting the s erver, wit hout any c ode change s to your applicatio n.</li> | |
| 1065 | </ ul> | |
| 1066 | ||
| 1067 | <h 3>Addition al Notes</ h3> | |
| 1068 | <u l> | |
| 1069 | <li>When a user atte mpts to ac cess a pro tected res ource for | |
| 1070 | the fi rst time, Tomcat 6 w ill call t he <code>a uthenticat e()</code> | |
| 1071 | method of this < code>Realm </code>. Thus, any changes yo u have mad e in | |
| 1072 | the se curity mec hanism dir ectly (new users, ch anged pass words or | |
| 1073 | roles, etc.) wil l be immed iately ref lected.</l i> | |
| 1074 | <li>Once a user has been authe nticated, the user ( and his or | |
| 1075 | her as sociated r oles) are cached wit hin Tomcat for the d uration of | |
| 1076 | the us er's login . For FOR M-based au thenticati on, that m eans until | |
| 1077 | the se ssion time s out or i s invalida ted; for B ASIC authe ntication, | |
| 1078 | that m eans until the user closes the ir browser . Any cha nges to th e | |
| 1079 | securi ty informa tion for a n already authentica ted user w ill <stron g>not</str ong> | |
| 1080 | be ref lected unt il the nex t time tha t user log s on again .</li> | |
| 1081 | <li>As wit h other <c ode>Realm< /code> imp lementatio ns, digest ed passwor ds | |
| 1082 | are su pported if the <code ><Realm ></code > element in <code>s erver.xml< /code> | |
| 1083 | contai ns a <code >digest</c ode> attri bute; JAAS Realm's <c ode>Callba ckHandler< /code> | |
| 1084 | will d igest the password p rior to pa ssing it b ack to the <code>Log inModule</ code></li> | |
| 1085 | </ ul> | |
| 1086 | ||
| 1087 | </blockquo te></td></ tr></table > | |
| 1088 | ||
| 1089 | ||
| 1090 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="C ombinedRea lm"><stron g>Combined Realm</str ong></a></ font></td> </tr><tr>< td><blockq uote> | |
| 1091 | ||
| 1092 | <h3>In troduction </h3> | |
| 1093 | ||
| 1094 | <p><st rong>Combi nedRealm</ strong> is an implem entation o f the Tomc at 6 | |
| 1095 | <code> Realm</cod e> interfa ce that au thenticate s users th rough one or more | |
| 1096 | sub-Re alms.</p> | |
| 1097 | ||
| 1098 | <p>Usi ng Combine dRealm giv es the dev eloper the ability t o combine multiple | |
| 1099 | Realms of the sa me or diff erent type s. This ca n be used to authent icate | |
| 1100 | agains t differen t sources, provide f all back i n case one Realm fai ls or for | |
| 1101 | any ot her purpos e that req uires mult iple Realm s.</p> | |
| 1102 | ||
| 1103 | <p>Sub -realms ar e defined by nesting <code>Rea lm</code> elements i nside the | |
| 1104 | <code> Realm</cod e> element that defi nes the Co mbinedReal m. Authent ication | |
| 1105 | will b e attempte d against each <code >Realm</co de> in the order the y are | |
| 1106 | listed . Authenti cation aga inst any R ealm will be suffici ent to aut henticate | |
| 1107 | the us er.</p> | |
| 1108 | ||
| 1109 | <h3>Re alm Elemen t Attribut es</h3> | |
| 1110 | <p>To configure a Combined Realm, you create a <code>< Realm>< /code> | |
| 1111 | elemen t and nest it in you r <code>$C ATALINA_BA SE/conf/se rver.xml</ code> | |
| 1112 | file w ithin your <code>< ;Engine> ;</code> o r <code>&l t;Host> </code>. | |
| 1113 | You ca n also nes t inside a <code>< ;Context&g t;</code> node in a | |
| 1114 | <code> context.xm l</code> f ile.</p> | |
| 1115 | ||
| 1116 | <h3>Exampl e</h3> | |
| 1117 | ||
| 1118 | <p>Here is an exampl e of how y our server .xml snipp et should look to us e a | |
| 1119 | UserDataba se Realm a nd a DataS ource Real m.</p> | |
| 1120 | ||
| 1121 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 1122 | <Realm className= "org.apach e.catalina .realm.Com binedRealm " > | |
| 1123 | <Rea lm classNa me="org.ap ache.catal ina.realm. UserDataba seRealm" | |
| 1124 | resourc eName="Use rDatabase" /> | |
| 1125 | <Rea lm classNa me="org.ap ache.catal ina.realm. DataSource Realm" | |
| 1126 | dataSou rceName="j dbc/author ity" | |
| 1127 | userTab le="users" userNameC ol="user_n ame" userC redCol="us er_pass" | |
| 1128 | userRol eTable="us er_roles" roleNameCo l="role_na me"/> | |
| 1129 | </Realm > | |
| 1130 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 1131 | ||
| 1132 | </blockquo te></td></ tr></table > | |
| 1133 | ||
| 1134 | <table bor der="0" ce llspacing= "0" cellpa dding="2"> <tr><td bg color="#82 8DA6"><fon t color="# ffffff" fa ce="arial, helvetica. sanserif"> <a name="L ockOutReal m"><strong >LockOutRe alm</stron g></a></fo nt></td></ tr><tr><td ><blockquo te> | |
| 1135 | ||
| 1136 | <h3>In troduction </h3> | |
| 1137 | ||
| 1138 | <p><st rong>LockO utRealm</s trong> is an impleme ntation of the Tomca t 6 | |
| 1139 | <code> Realm</cod e> interfa ce that ex tends the CombinedRe alm to pro vide lock | |
| 1140 | out fu nctionalit y to provi de a user lock out m echanism i f there ar e too many | |
| 1141 | failed authentic ation atte mpts in a given peri od of time .</p> | |
| 1142 | ||
| 1143 | <p>To ensure cor rect opera tion, ther e is a rea sonable de gree of | |
| 1144 | synchr onisation in this Re alm.</p> | |
| 1145 | ||
| 1146 | <p>Thi s Realm do es not req uire modif ication to the under lying Real ms or the | |
| 1147 | associ ated user storage me chanisms. It achieve s this by recording all failed | |
| 1148 | logins , includin g those fo r users th at do not exist. To prevent a DOS by | |
| 1149 | delibe rating mak ing reques ts with in valid user s (and hen ce causing this | |
| 1150 | cache to grow) t he size of the list of users t hat have f ailed auth entication | |
| 1151 | is lim ited.</p> | |
| 1152 | ||
| 1153 | <p>Sub -realms ar e defined by nesting <code>Rea lm</code> elements i nside the | |
| 1154 | <code> Realm</cod e> element that defi nes the Lo ckOutRealm . Authenti cation | |
| 1155 | will b e attempte d against each <code >Realm</co de> in the order the y are | |
| 1156 | listed . Authenti cation aga inst any R ealm will be suffici ent to aut henticate | |
| 1157 | the us er.</p> | |
| 1158 | ||
| 1159 | <h3>Re alm Elemen t Attribut es</h3> | |
| 1160 | <p>To configure a LockOutR ealm, you create a < code><R ealm></ code> | |
| 1161 | elemen t and nest it in you r <code>$C ATALINA_BA SE/conf/se rver.xml</ code> | |
| 1162 | file w ithin your <code>< ;Engine> ;</code> o r <code>&l t;Host> </code>. | |
| 1163 | You ca n also nes t inside a <code>< ;Context&g t;</code> node in a | |
| 1164 | <code> context.xm l</code> f ile. The a ttributes for the | |
| 1165 | LockOu tRealm are defined i n the <a h ref="confi g/realm.ht ml">Realm< /a> | |
| 1166 | config uration do cumentatio n.</p> | |
| 1167 | ||
| 1168 | <h3>Exampl e</h3> | |
| 1169 | ||
| 1170 | <p>Here is an exampl e of how y our server .xml snipp et should look to ad d lock out | |
| 1171 | functional ity to a U serDatabas e Realm.</ p> | |
| 1172 | ||
| 1173 | <div align ="left"><t able cells pacing="4" cellpaddi ng="0" bor der="0"><t r><td bgco lor="#0232 64" width= "1" height ="1"><img src="./ima ges/void.g if" alt="" width="1" height="1 " vspace=" 0" hspace= "0" border ="0"></td> <td bgcolo r="#023264 " height=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td><t d bgcolor= "#023264" width="1" height="1" ><img src= "./images/ void.gif" alt="" wid th="1" hei ght="1" vs pace="0" h space="0" border="0" ></td></tr ><tr><td b gcolor="#0 23264" wid th="1"><im g src="./i mages/void .gif" alt= "" width=" 1" height= "1" vspace ="0" hspac e="0" bord er="0"></t d><td bgco lor="#ffff ff" height ="1"><pre> | |
| 1174 | <Realm className= "org.apach e.catalina .realm.Loc kOutRealm" > | |
| 1175 | <Rea lm classNa me="org.ap ache.catal ina.realm. UserDataba seRealm" | |
| 1176 | resourc eName="Use rDatabase" /> | |
| 1177 | </Realm > | |
| 1178 | </pre></td ><td bgcol or="#02326 4" width=" 1"><img sr c="./image s/void.gif " alt="" w idth="1" h eight="1" vspace="0" hspace="0 " border=" 0"></td></ tr><tr><td bgcolor=" #023264" w idth="1" h eight="1"> <img src=" ./images/v oid.gif" a lt="" widt h="1" heig ht="1" vsp ace="0" hs pace="0" b order="0"> </td><td b gcolor="#0 23264" hei ght="1"><i mg src="./ images/voi d.gif" alt ="" width= "1" height ="1" vspac e="0" hspa ce="0" bor der="0"></ td><td bgc olor="#023 264" width ="1" heigh t="1"><img src="./im ages/void. gif" alt=" " width="1 " height=" 1" vspace= "0" hspace ="0" borde r="0"></td ></tr></ta ble></div> | |
| 1179 | ||
| 1180 | </blockquo te></td></ tr></table > | |
| 1181 | ||
| 1182 | </blockquo te></td></ tr></table ></td></tr ><!--FOOTE R SEPARATO R--><tr><t d colspan= "2"><hr no shade="nos hade" size ="1"></td> </tr><!--P AGE FOOTER --><tr><td colspan=" 2"><div al ign="cente r"><font c olor="#525 D76" size= "-1"><em> | |
| 1183 | Co pyright &c opy; 1999- 2013, Apac he Softwar e Foundati on | |
| 1184 | </ em></font> </div></td ></tr></ta ble></body ></html> |
Araxis Merge (but not the data content of this report) is Copyright © 1993-2016 Araxis Ltd (www.araxis.com). All rights reserved.