acegi.xml 267 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
  4. <!--
  5. * ========================================================================
  6. *
  7. * Copyright 2004 Acegi Technology Pty Limited
  8. *
  9. * Licensed under the Apache License, Version 2.0 (the "License");
  10. * you may not use this file except in compliance with the License.
  11. * You may obtain a copy of the License at
  12. *
  13. * http://www.apache.org/licenses/LICENSE-2.0
  14. *
  15. * Unless required by applicable law or agreed to in writing, software
  16. * distributed under the License is distributed on an "AS IS" BASIS,
  17. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18. * See the License for the specific language governing permissions and
  19. * limitations under the License.
  20. *
  21. * ========================================================================
  22. -->
  23. <book>
  24. <bookinfo>
  25. <title>Acegi Security System for Spring</title>
  26. <subtitle>Reference Documentation</subtitle>
  27. <releaseinfo>0.9.0</releaseinfo>
  28. <authorgroup>
  29. <author>
  30. <firstname>Ben</firstname>
  31. <surname>Alex</surname>
  32. </author>
  33. </authorgroup>
  34. </bookinfo>
  35. <toc></toc>
  36. <preface id="preface">
  37. <title>Preface</title>
  38. <para>This document provides a reference guide to the Acegi Security
  39. System for Spring, which is a series of classes that deliver
  40. authentication and authorization services within the Spring
  41. Framework.</para>
  42. <para>I would like to acknowledge this reference was prepared using the
  43. DocBook configuration included with the Spring Framework. The Spring team
  44. in turn acknowledge Chris Bauer (Hibernate) for his assistance with their
  45. DocBook.</para>
  46. </preface>
  47. <chapter id="security">
  48. <title>Security</title>
  49. <sect1 id="security-before-you-begin">
  50. <title>Before You Begin</title>
  51. <para>For your security, each official release JAR of Acegi Security has
  52. been signed by the project leader. This does not in any way alter the
  53. liability disclaimer contained in the License, but it does ensure you
  54. are using a properly reviewed, official build of Acegi Security. Please
  55. refer to the <literal>readme.txt</literal> file in the root of the
  56. release distribution for instructions on how to validate the JARs are
  57. correctly signed, and which certificate has been used to sign
  58. them.</para>
  59. </sect1>
  60. <sect1 id="security-introduction">
  61. <title>Introduction</title>
  62. <para>The Acegi Security System for Spring provides authentication and
  63. authorization capabilities for Spring-powered projects, with optional
  64. integration with popular web containers. The security architecture was
  65. designed from the ground up using "The Spring Way" of development, which
  66. includes using bean contexts, interceptors and interface-driven
  67. programming. As a consequence, the Acegi Security System for Spring is
  68. useful out-of-the-box for those seeking to secure their Spring-based
  69. applications, and can be easily adapted to complex customized
  70. requirements.</para>
  71. <para>Security involves two distinct operations, authentication and
  72. authorization. The former relates to resolving whether or not a caller
  73. is who they claim to be. Authorization on the other hand relates to
  74. determining whether or not an authenticated caller is permitted to
  75. perform a given operation.</para>
  76. <para>Throughout the Acegi Security System for Spring, the user, system
  77. or agent that needs to be authenticated is referred to as a "principal".
  78. The security architecture does not have a notion of roles or groups,
  79. which you may be familiar with from other security implementations,
  80. although equivalent functionality is fully accommodated by Acegi
  81. Security.</para>
  82. <sect2 id="security-introduction-status">
  83. <title>Current Status</title>
  84. <para>The Acegi Security System for Spring is widely used by members
  85. of the Spring Community. The APIs are considered stable and only minor
  86. changes are expected. Having said that, like many other projects we
  87. need to strike a balance between backward compatibility and
  88. improvement. Effective version 0.6.1, Acegi Security uses the Apache
  89. Portable Runtime Project versioning guidelines, available from
  90. <literal>http://apr.apache.org/versioning.html</literal>.</para>
  91. <para>Some minor improvements are currently intended prior to the
  92. 1.0.0 release, although each of these represent additional
  93. functionality that will in no way modify the project's central
  94. interfaces or classes. Users of Acegi Security System for Spring
  95. should therefore be comfortable depending on the current version of
  96. the project in their applications.</para>
  97. </sect2>
  98. </sect1>
  99. <sect1 id="security-high-level-design">
  100. <title>High Level Design</title>
  101. <sect2 id="security-high-level-design-key-components">
  102. <title>Key Components</title>
  103. <para>Most enterprise applications have four basic security
  104. requirements. First, they need to be able to authenticate a principal.
  105. Second, they need to be able to secure web requests. Third, enterprise
  106. applications need to be able to secure services layer methods.
  107. Finally, quite often an enterprise application will need to secure
  108. domain object instances. Acegi Security provides a comprehensive
  109. framework for achieving all of these four common enterprise
  110. application security requirements.</para>
  111. <para>The Acegi Security System for Spring essentially comprises eight
  112. key functional parts:</para>
  113. <itemizedlist spacing="compact">
  114. <listitem>
  115. <para>An <literal>Authentication</literal> object which holds the
  116. principal, credentials and the authorities granted to the
  117. principal. The object can also store additional information
  118. associated with an authentication request, such as the source
  119. TCP/IP address.</para>
  120. </listitem>
  121. <listitem>
  122. <para>A <literal>ContextHolder</literal> which holds the
  123. <literal>Authentication</literal> object in a
  124. <literal>ThreadLocal</literal>-bound object.</para>
  125. </listitem>
  126. <listitem>
  127. <para>An <literal>AuthenticationManager</literal> to authenticate
  128. the <literal>Authentication</literal> object presented via the
  129. <literal>ContextHolder</literal>.</para>
  130. </listitem>
  131. <listitem>
  132. <para>An <literal>AccessDecisionManager</literal> to authorize a
  133. given operation.</para>
  134. </listitem>
  135. <listitem>
  136. <para>A <literal>RunAsManager</literal> to optionally replace the
  137. <literal>Authentication</literal> object whilst a given operation
  138. is being executed.</para>
  139. </listitem>
  140. <listitem>
  141. <para>A "secure object" interceptor, which coordinates the
  142. authentication, authorization, run-as replacement, after
  143. invocation handling and execution of a given operation.</para>
  144. </listitem>
  145. <listitem>
  146. <para>An <literal>AfterInvocationManager</literal> which can
  147. modify an <literal>Object</literal> returned from a "secure
  148. object" invocation, such as removing <literal>Collection</literal>
  149. elements a principal does not have authority to access.</para>
  150. </listitem>
  151. <listitem>
  152. <para>An acess control list (ACL) management package, which can be
  153. used to obtain the ACLs applicable for domain object
  154. instances.</para>
  155. </listitem>
  156. </itemizedlist>
  157. <para>A "secure object" interceptor executes most of the Acegi
  158. Security key classes and in doing so delivers the framework's major
  159. features. Given its importance, Figure 1 shows the key relationships
  160. and concrete implementations of
  161. <literal>AbstractSecurityInterceptor</literal>.</para>
  162. <para><mediaobject>
  163. <imageobject role="html">
  164. <imagedata align="center"
  165. fileref="images/SecurityInterception.gif"
  166. format="GIF" />
  167. </imageobject>
  168. <caption>
  169. <para>Figure 1: The key "secure object" model</para>
  170. </caption>
  171. </mediaobject></para>
  172. <para>Each "secure object" interceptor (hereinafter called a "security
  173. interceptor") works with a particular type of "secure object". So,
  174. what is a secure object? Secure objects refer to any type of object
  175. that can have security applied to it. A secure object must provide
  176. some form of callback, so that the security interceptor can
  177. transparently do its work as required, and callback the object when it
  178. is time for it to proceed with the requested operation. If secure
  179. objects cannot provide a native callback approach, a wrapper needs to
  180. be written so this becomes possible.</para>
  181. <para>Each secure object has its own package under
  182. <literal>net.sf.acegisecurity.intercept</literal>. Every other package
  183. in the security system is secure object independent, in that it can
  184. support any type of secure object presented.</para>
  185. <para>Only developers contemplating an entirely new way of
  186. intercepting and authorizing requests would need to use secure objects
  187. directly. For example, it would be possible to build a new secure
  188. object to secure calls to a messaging system that does not use
  189. <literal>MethodInvocation</literal>s. Most Spring applications will
  190. simply use the three currently supported secure object types (AOP
  191. Alliance <literal>MethodInvocation</literal>, AspectJ
  192. <literal>JoinPoint</literal> and web request
  193. <literal>FilterInterceptor</literal>) with complete
  194. transparency.</para>
  195. <para>Each of the eight key parts of Acegi Security are discussed in
  196. detail throughout this document.</para>
  197. </sect2>
  198. <sect2 id="security-high-level-design-supported-secure-objects">
  199. <title>Supported Secure Objects</title>
  200. <para>As shown in the base of Figure 1, the Acegi Security System for
  201. Spring currently supports three secure objects.</para>
  202. <para>The first handles an AOP Alliance
  203. <literal>MethodInvocation</literal>. This is the secure object type
  204. used to protect Spring beans. Developers will generally use this
  205. secure object type to secure their business objects. To make a
  206. standard Spring-hosted bean available as a
  207. <literal>MethodInvocation</literal>, the bean is simply published
  208. through a <literal>ProxyFactoryBean</literal> or
  209. <literal>BeanNameAutoProxyCreator</literal> or
  210. <literal>DefaultAdvisorAutoProxyCreator</literal>. Most Spring
  211. developers would already be familiar with these due to their use in
  212. transactions and other areas of Spring.</para>
  213. <para>The second type is an AspectJ <literal>JoinPoint</literal>.
  214. AspectJ has a particular use in securing domain object instances, as
  215. these are most often managed outside the Spring bean container. By
  216. using AspectJ, standard constructs such as <literal>new
  217. Person();</literal> can be used and full security will be applied to
  218. them by Acegi Security. The
  219. <literal>AspectJSecurityInterceptor</literal> is still managed by
  220. Spring, which creates the aspect singleton and wires it with the
  221. appropriate authentication managers, access decision managers and so
  222. on.</para>
  223. <para>The third type is a <literal>FilterInvocation</literal>. This is
  224. an object included with the Acegi Security System for Spring. It is
  225. created by an included filter and simply wraps the HTTP
  226. <literal>ServletRequest</literal>, <literal>ServletResponse</literal>
  227. and <literal>FilterChain</literal>. The
  228. <literal>FilterInvocation</literal> enables HTTP resources to be
  229. secured. Developers do not usually need to understand the mechanics of
  230. how this works, because they just add the filters to their
  231. <literal>web.xml</literal> and let the security system do its
  232. work.</para>
  233. </sect2>
  234. <sect2 id="security-high-level-design-configuration-attributes">
  235. <title>Configuration Attributes</title>
  236. <para>Every secure object can represent an infinite number of
  237. individual requests. For example, a
  238. <literal>MethodInvocation</literal> can represent the invocation of
  239. any method with any arguments, whilst a
  240. <literal>FilterInvocation</literal> can represent any HTTP URL.</para>
  241. <para>The Acegi Security System for Spring needs to record the
  242. configuration that applies to each of these possible requests. The
  243. security configuration of a request to
  244. <literal>BankManager.getBalance(int accountNumber)</literal> needs to
  245. be very different from the security configuration of a request to
  246. <literal>BankManager.approveLoan(int applicationNumber)</literal>.
  247. Similarly, the security configuration of a request to
  248. <literal>http://some.bank.com/index.htm</literal> needs to be very
  249. different from the security configuration of
  250. <literal>http://some.bank.com/manage/timesheet.jsp</literal>.</para>
  251. <para>To store the various security configurations associated with
  252. different requests, a configuration attribute is used. At an
  253. implementation level a configuration attribute is represented by the
  254. <literal>ConfigAttribute</literal> interface. One concrete
  255. implementation of <literal>ConfigAttribute</literal> is provided,
  256. <literal>SecurityConfig</literal>, which simply stores a configuration
  257. attribute as a <literal>String</literal>.</para>
  258. <para>The collection of <literal>ConfigAttribute</literal>s associated
  259. with a particular request is held in a
  260. <literal>ConfigAttributeDefinition</literal>. This concrete class is
  261. simply a holder of <literal>ConfigAttribute</literal>s and does
  262. nothing special.</para>
  263. <para>When a request is received by the security interceptor, it needs
  264. to determine which configuration attributes apply. In other words, it
  265. needs to find the <literal>ConfigAttributeDefinition</literal> which
  266. applies to the request. This decision is handled by the
  267. <literal>ObjectDefinitionSource</literal> interface. The main method
  268. provided by this interface is <literal>public
  269. ConfigAttributeDefinition getAttributes(Object object)</literal>, with
  270. the <literal>Object</literal> being the secure object. Recall the
  271. secure object contains details of the request, so the
  272. <literal>ObjectDefinitionSource</literal> implementation will be able
  273. to extract the details it requires to lookup the relevant
  274. <literal>ConfigAttributeDefinition</literal>.</para>
  275. </sect2>
  276. </sect1>
  277. <sect1 id="security-request-contexts">
  278. <title>Request Contexts</title>
  279. <sect2 id="security-contexts-history">
  280. <title>Historical Approach</title>
  281. <para>Prior to release 0.9.0, Acegi Security used a
  282. <literal>ContextHolder</literal> to store a <literal>Context</literal>
  283. between sessions. A particular subclass of <literal>Context</literal>,
  284. <literal>SecureContext</literal> defined an interface used for storage
  285. of the <literal>Authentication</literal> object. The
  286. <literal>ContextHolder</literal> was a <literal>ThreadLocal</literal>.
  287. This was removed from 0.9.0 after discussion with other Spring
  288. developers for the sake of consistency. See for example
  289. <literal>http://article.gmane.org/gmane.comp.java.springframework.devel/8290</literal>.
  290. This history is mentioned as the long period
  291. <literal>ContextHolder</literal> was used will likely mean that
  292. certain documentation you encounter concerning Acegi Security might
  293. still refer to <literal>ContextHolder</literal>. Generally you can
  294. just substitute "<literal>SecurityContextHolder</literal>" for
  295. "<literal>ContextHolder</literal>", and
  296. "<literal>SecurityContext</literal>" for
  297. "<literal>SecureContext</literal>", and you'll have the primary
  298. meaning of such documentation.</para>
  299. </sect2>
  300. <sect2 id="security-contexts-security-context">
  301. <title>SecurityContext</title>
  302. <para>The Acegi Security System for Spring uses a
  303. <literal>SecurityContextHolder</literal> to store the
  304. <literal>SecurityContext</literal>. The
  305. <literal>SecurityContext</literal> contains a single getter/setter for
  306. <literal>Authentication</literal>. All Acegi Security classes query
  307. the <literal>SecurityContextHolder</literal> for obtaining the current
  308. <literal>SecurityContext</literal> (and in turn the principal).
  309. <literal>SecurityContextHolder</literal> is an
  310. <literal>InheritableThreadLocal</literal>, meaning it is associated
  311. with the current thread of execution.</para>
  312. </sect2>
  313. <sect2 id="security-contexts-storage">
  314. <title>Context Storage</title>
  315. <para>Central to Acegi Security's design is that the contents of the
  316. <literal>SecurityContextHolder</literal> (which is simply a
  317. <literal>SecurityContext</literal> implementation) can be stored
  318. between web requests. This is so that a successfully authenticated
  319. principal can be identified on subsequent requests through the
  320. <literal>Authentication</literal> stored inside the
  321. <literal>SecurityContext</literal> obtained from the
  322. <literal>SecurityContextHolder</literal>. The
  323. <literal>HttpSessionContextIntegrationFilter</literal> exists to
  324. automatically copy the contents of a well-defined
  325. <literal>HttpSession</literal> attribute into the
  326. <literal>SecurityContextHolder</literal>, then at the end of each
  327. request, copy the <literal>SecurityContextHolder</literal> contents
  328. back into the <literal>HttpSession</literal> ready for next
  329. request.</para>
  330. <para>It is essential - and an extremely common error of end users -
  331. that <literal>HttpSessionContextIntegrationFilter</literal> appears
  332. before any other Acegi Security filter. Acegi Security filters expect
  333. to be able to modify the <literal>SecurityContextHolder</literal>
  334. contents as they see fit, and something else (namely
  335. <literal>HttpSessionContextIntegrationFilter</literal>) will store
  336. those between requests if necessary. This is why
  337. <literal>HttpSessionContextIntegrationFilter</literal> must be the
  338. first filter used.</para>
  339. <para>You can define a custom <literal>SecurityContext</literal>
  340. implementation be used in your application by setting the
  341. <literal>context</literal> property on the
  342. <literal>HttpSessionContextIntegrationFilter</literal> bean.</para>
  343. </sect2>
  344. </sect1>
  345. <sect1 id="security-interception">
  346. <title>Security Interception</title>
  347. <sect2 id="security-interception-all-secure-objects">
  348. <title>All Secure Objects</title>
  349. <para>As described in the High Level Design section, each secure
  350. object has its own security interceptor which is responsible for
  351. handling each request. Handling involves a number of
  352. operations:</para>
  353. <orderedlist>
  354. <listitem>
  355. <para>Store the configuration attributes that are associated with
  356. each secure request.</para>
  357. </listitem>
  358. <listitem>
  359. <para>Extract the <literal>ConfigAttributeDefinition</literal>
  360. that applies to the request from the relevant
  361. <literal>ObjectDefinitionSource</literal>.</para>
  362. </listitem>
  363. <listitem>
  364. <para>Obtain the <literal>Authentication</literal> object from the
  365. <literal>SecureContext</literal>, which is held in the
  366. <literal>ContextHolder</literal>.</para>
  367. </listitem>
  368. <listitem>
  369. <para>Pass the <literal>Authentication</literal> object to the
  370. <literal>AuthenticationManager</literal>, update the
  371. <literal>ContextHolder</literal> with the response.</para>
  372. </listitem>
  373. <listitem>
  374. <para>Pass the <literal>Authentication</literal> object, the
  375. <literal>ConfigAttributeDefinition</literal>, and the secure
  376. object to the <literal>AccessDecisionManager</literal>.</para>
  377. </listitem>
  378. <listitem>
  379. <para>Pass the <literal>Authentication</literal> object, the
  380. <literal>ConfigAttributeDefinition</literal>, and the secure
  381. object to the <literal>RunAsManager</literal>.</para>
  382. </listitem>
  383. <listitem>
  384. <para>If the <literal>RunAsManager</literal> returns a new
  385. <literal>Authentication</literal> object, update the
  386. <literal>ContextHolder</literal> with it.</para>
  387. </listitem>
  388. <listitem>
  389. <para>Proceed with the request execution of the secure
  390. object.</para>
  391. </listitem>
  392. <listitem>
  393. <para>If the <literal>RunAsManager</literal> earlier returned a
  394. new <literal>Authentication</literal> object, update the
  395. <literal>ContextHolder</literal> with the
  396. <literal>Authentication</literal> object that was previously
  397. returned by the <literal>AuthenticationManager</literal>.</para>
  398. </listitem>
  399. <listitem>
  400. <para>If an <literal>AfterInvocationManager</literal> is defined,
  401. pass it the result of the secure object execution so that it may
  402. throw an <literal>AccessDeniedException</literal> or mutate the
  403. returned object if required.</para>
  404. </listitem>
  405. <listitem>
  406. <para>Return any result received from the
  407. <literal>AfterInvocationManager</literal>, or if no
  408. <literal>AfterInvocationManager</literal> is defined, simply
  409. return the result provided by the secure object execution.</para>
  410. </listitem>
  411. </orderedlist>
  412. <para>Whilst this may seem quite involved, don't worry. Developers
  413. interact with the security process by simply implementing basic
  414. interfaces (such as <literal>AccessDecisionManager</literal>), which
  415. are fully discussed below.</para>
  416. <para>The <literal>AbstractSecurityInterceptor</literal> handles the
  417. majority of the flow listed above. As shown in Figure 1, each secure
  418. object has its own security interceptor which subclasses
  419. <literal>AbstractSecurityInterceptor</literal>. Each of these secure
  420. object-specific security interceptors are discussed below.</para>
  421. </sect2>
  422. <sect2 id="security-interception-aopalliance">
  423. <title>AOP Alliance (MethodInvocation) Security Interceptor</title>
  424. <para>To secure <literal>MethodInvocation</literal>s, developers
  425. simply add a properly configured
  426. <literal>MethodSecurityInterceptor</literal> into the application
  427. context. Next the beans requiring security are chained into the
  428. interceptor. This chaining is accomplished using Spring’s
  429. <literal>ProxyFactoryBean</literal> or
  430. <literal>BeanNameAutoProxyCreator</literal>, as commonly used by many
  431. other parts of Spring (refer to the sample application for examples).
  432. Alternatively, Acegi Security provides a
  433. <literal>MethodDefinitionSourceAdvisor</literal> which may be used
  434. with Spring's <literal>DefaultAdvisorAutoProxyCreator</literal> to
  435. automatically chain the security interceptor in front of any beans
  436. defined against the <literal>MethodSecurityInterceptor</literal>. The
  437. <literal>MethodSecurityInterceptor</literal> itself is configured as
  438. follows:</para>
  439. <para><programlisting>&lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
  440. &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
  441. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  442. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  443. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  444. &lt;property name="afterInvocationManager"&gt;&lt;ref bean="afterInvocationManager"/&gt;&lt;/property&gt;
  445. &lt;property name="objectDefinitionSource"&gt;
  446. &lt;value&gt;
  447. net.sf.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
  448. net.sf.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
  449. &lt;/value&gt;
  450. &lt;/property&gt;
  451. &lt;/bean&gt;</programlisting></para>
  452. <para>As shown above, the <literal>MethodSecurityInterceptor</literal>
  453. is configured with a reference to an
  454. <literal>AuthenticationManager</literal>,
  455. <literal>AccessDecisionManager</literal> and
  456. <literal>RunAsManager</literal>, which are each discussed in separate
  457. sections below. In this case we've also defined an
  458. <literal>AfterInvocationManager</literal>, although this is entirely
  459. optional. The <literal>MethodSecurityInterceptor</literal> is also
  460. configured with configuration attributes that apply to different
  461. method signatures. A full discussion of configuration attributes is
  462. provided in the High Level Design section of this document.</para>
  463. <para>The <literal>MethodSecurityInterceptor</literal> can be
  464. configured with configuration attributes in three ways. The first is
  465. via a property editor and the application context, which is shown
  466. above. The second is via defining the configuration attributes in your
  467. source code using Jakarta Commons Attributes or Java 5 Annotations.
  468. The third is via writing your own
  469. <literal>ObjectDefinitionSource</literal>, although this is beyond the
  470. scope of this document. Irrespective of the approach used, the
  471. <literal>ObjectDefinitionSource</literal> is responsible for returning
  472. a <literal>ConfigAttributeDefinition</literal> object that contains
  473. all of the configuration attributes associated with a single secure
  474. method.</para>
  475. <para>It should be noted that the
  476. <literal>MethodSecurityInterceptor.setObjectDefinitionSource()</literal>
  477. method actually expects an instance of
  478. <literal>MethodDefinitionSource</literal>. This is a marker interface
  479. which subclasses <literal>ObjectDefinitionSource</literal>. It simply
  480. denotes the <literal>ObjectDefinitionSource</literal> understands
  481. <literal>MethodInvocation</literal>s. In the interests of simplicity
  482. we'll continue to refer to the
  483. <literal>MethodDefinitionSource</literal> as an
  484. <literal>ObjectDefinitionSource</literal>, as the distinction is of
  485. little relevance to most users of the
  486. <literal>MethodSecurityInterceptor</literal>.</para>
  487. <para>If using the application context property editor approach (as
  488. shown above), commas are used to delimit the different configuration
  489. attributes that apply to a given method pattern. Each configuration
  490. attribute is assigned into its own <literal>SecurityConfig</literal>
  491. object. The <literal>SecurityConfig</literal> object is discussed in
  492. the High Level Design section.</para>
  493. <para>If you are using the Jakarta Commons Attributes approach, your
  494. bean context will be configured differently:</para>
  495. <para><programlisting>&lt;bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes"/&gt;
  496. &lt;bean id="objectDefinitionSource" class="net.sf.acegisecurity.intercept.method.MethodDefinitionAttributes"&gt;
  497. &lt;property name="attributes"&gt;&lt;ref local="attributes"/&gt;&lt;/property&gt;
  498. &lt;/bean&gt;
  499. &lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
  500. &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
  501. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  502. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  503. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  504. &lt;property name="objectDefinitionSource"&gt;&lt;ref bean="objectDefinitionSource"/&gt;&lt;/property&gt;
  505. &lt;/bean&gt;</programlisting></para>
  506. <para>In addition, your source code will contain Jakarta Commons
  507. Attributes tags that refer to a concrete implementation of
  508. <literal>ConfigAttribute</literal>. The following example uses the
  509. <literal>SecurityConfig</literal> implementation to represent the
  510. configuration attributes, and results in the same security
  511. configuration as provided by the property editor approach
  512. above:</para>
  513. <para><programlisting>public interface BankManager {
  514. /**
  515. * @@SecurityConfig("ROLE_SUPERVISOR")
  516. * @@SecurityConfig("RUN_AS_SERVER")
  517. */
  518. public void deleteSomething(int id);
  519. /**
  520. * @@SecurityConfig("ROLE_SUPERVISOR")
  521. * @@SecurityConfig("RUN_AS_SERVER")
  522. */
  523. public void deleteAnother(int id);
  524. /**
  525. * @@SecurityConfig("ROLE_TELLER")
  526. * @@SecurityConfig("ROLE_SUPERVISOR")
  527. * @@SecurityConfig("BANKSECURITY_CUSTOMER")
  528. * @@SecurityConfig("RUN_AS_SERVER")
  529. */
  530. public float getBalance(int id);
  531. }</programlisting></para>
  532. <para>If you are using the Spring Security Java 5 Annotations
  533. approach, your bean context will be configured as follows:</para>
  534. <para><programlisting>&lt;bean id="attributes" class="net.sf.acegisecurity.annotation.SecurityAnnotationAttributes"/&gt;
  535. &lt;bean id="objectDefinitionSource" class="net.sf.acegisecurity.intercept.method.MethodDefinitionAttributes"&gt;
  536. &lt;property name="attributes"&gt;&lt;ref local="attributes"/&gt;&lt;/property&gt;
  537. &lt;/bean&gt;
  538. &lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
  539. &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
  540. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  541. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  542. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  543. &lt;property name="objectDefinitionSource"&gt;&lt;ref bean="objectDefinitionSource"/&gt;&lt;/property&gt;
  544. &lt;/bean&gt;</programlisting></para>
  545. <para>In addition, your source code will contain the Acegi Java 5
  546. Security Annotations that represent the
  547. <literal>ConfigAttribute</literal>. The following example uses the
  548. <literal>@Secured</literal> annotations to represent the configuration
  549. attributes, and results in the same security configuration as provided
  550. by the property editor approach:</para>
  551. <para><programlisting>import net.sf.acegisecurity.annotation.Secured;
  552. public interface BankManager {
  553. /**
  554. * Delete something
  555. */
  556. @Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
  557. public void deleteSomething(int id);
  558. /**
  559. * Delete another
  560. */
  561. @Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
  562. public void deleteAnother(int id);
  563. /**
  564. * Get balance
  565. */
  566. @Secured({"ROLE_TELLER","ROLE_SUPERVISOR","BANKSECURITY_CUSTOMER","RUN_AS_SERVER" })
  567. public float getBalance(int id);
  568. }</programlisting></para>
  569. <para>You might have noticed the
  570. <literal>validateConfigAttributes</literal> property in the above
  571. <literal>MethodSecurityInterceptor</literal> examples. When set to
  572. <literal>true</literal> (the default), at startup time the
  573. <literal>MethodSecurityInterceptor</literal> will evaluate if the
  574. provided configuration attributes are valid. It does this by checking
  575. each configuration attribute can be processed by either the
  576. <literal>AccessDecisionManager</literal> or the
  577. <literal>RunAsManager</literal>. If neither of these can process a
  578. given configuration attribute, an exception is thrown. If using the
  579. Jakarta Commons Attributes method of configuration, you should set
  580. <literal>validateConfigAttributes</literal> to
  581. <literal>false</literal>.</para>
  582. </sect2>
  583. <sect2 id="security-interception-aspectj">
  584. <title>AspectJ (JoinPoint) Security Interceptor</title>
  585. <para>The AspectJ security interceptor is very similar to the AOP
  586. Alliance security interceptor discussed in the previous section.
  587. Indeed we will only discuss the differences in this section.</para>
  588. <para>The AspectJ interceptor is named
  589. <literal>AspectJSecurityInterceptor</literal>. Unlike the AOP Alliance
  590. security interceptor, which relies on the Spring application context
  591. to weave in the security interceptor via proxying, the
  592. <literal>AspectJSecurityInterceptor</literal> is weaved in via the
  593. AspectJ compiler. It would not be uncommon to use both types of
  594. security interceptors in the same application, with
  595. <literal>AspectJSecurityInterceptor</literal> being used for domain
  596. object instance security and the AOP Alliance
  597. <literal>MethodSecurityInterceptor</literal> being used for services
  598. layer security.</para>
  599. <para>Let's first consider how the
  600. <literal>AspectJSecurityInterceptor</literal> is configured in the
  601. Spring application context:</para>
  602. <para><programlisting>&lt;bean id="bankManagerSecurity" class="net.sf.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor"&gt;
  603. &lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
  604. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  605. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  606. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  607. &lt;property name="afterInvocationManager"&gt;&lt;ref bean="afterInvocationManager"/&gt;&lt;/property&gt;
  608. &lt;property name="objectDefinitionSource"&gt;
  609. &lt;value&gt;
  610. net.sf.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
  611. net.sf.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
  612. &lt;/value&gt;
  613. &lt;/property&gt;
  614. &lt;/bean&gt;</programlisting></para>
  615. <para>As you can see, aside from the class name, the
  616. <literal>AspectJSecurityInterceptor</literal> is exactly the same as
  617. the AOP Alliance security interceptor. Indeed the two interceptors can
  618. share the same <literal>objectDefinitionSource</literal>, as the
  619. <literal>ObjectDefinitionSource</literal> works with
  620. <literal>java.lang.reflect.Method</literal>s rather than an AOP
  621. library-specific class. Of course, your access decisions have access
  622. to the relevant AOP library-specific invocation (ie
  623. <literal>MethodInvocation</literal> or <literal>JoinPoint</literal>)
  624. and as such can consider a range of addition criteria when making
  625. access decisions (such as method arguments).</para>
  626. <para>Next you'll need to define an AspectJ <literal>aspect</literal>.
  627. For example:</para>
  628. <para><programlisting>package net.sf.acegisecurity.samples.aspectj;
  629. import net.sf.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor;
  630. import net.sf.acegisecurity.intercept.method.aspectj.AspectJCallback;
  631. import org.springframework.beans.factory.InitializingBean;
  632. public aspect DomainObjectInstanceSecurityAspect implements InitializingBean {
  633. private AspectJSecurityInterceptor securityInterceptor;
  634. pointcut domainObjectInstanceExecution(): target(PersistableEntity)
  635. &amp;&amp; execution(public * *(..)) &amp;&amp; !within(DomainObjectInstanceSecurityAspect);
  636. Object around(): domainObjectInstanceExecution() {
  637. if (this.securityInterceptor != null) {
  638. AspectJCallback callback = new AspectJCallback() {
  639. public Object proceedWithObject() {
  640. return proceed();
  641. }
  642. };
  643. return this.securityInterceptor.invoke(thisJoinPoint, callback);
  644. } else {
  645. return proceed();
  646. }
  647. }
  648. public AspectJSecurityInterceptor getSecurityInterceptor() {
  649. return securityInterceptor;
  650. }
  651. public void setSecurityInterceptor(AspectJSecurityInterceptor securityInterceptor) {
  652. this.securityInterceptor = securityInterceptor;
  653. }
  654. public void afterPropertiesSet() throws Exception {
  655. if (this.securityInterceptor == null)
  656. throw new IllegalArgumentException("securityInterceptor required");
  657. }
  658. }</programlisting></para>
  659. <para>In the above example, the security interceptor will be applied
  660. to every instance of <literal>PersistableEntity</literal>, which is an
  661. abstract class not shown (you can use any other class or
  662. <literal>pointcut</literal> expression you like). For those curious,
  663. <literal>AspectJCallback</literal> is needed because the
  664. <literal>proceed();</literal> statement has special meaning only
  665. within an <literal>around()</literal> body. The
  666. <literal>AspectJSecurityInterceptor</literal> calls this anonymous
  667. <literal>AspectJCallback</literal> class when it wants the target
  668. object to continue.</para>
  669. <para>You will need to configure Spring to load the aspect and wire it
  670. with the <literal>AspectJSecurityInterceptor</literal>. A bean
  671. declaration which achieves this is shown below:</para>
  672. <para><programlisting>&lt;bean id="domainObjectInstanceSecurityAspect"
  673. class="net.sf.acegisecurity.samples.aspectj.DomainObjectInstanceSecurityAspect"
  674. factory-method="aspectOf"&gt;
  675. &lt;property name="securityInterceptor"&gt;&lt;ref bean="aspectJSecurityInterceptor"/&gt;&lt;/property&gt;
  676. &lt;/bean&gt;</programlisting></para>
  677. <para>That's it! Now you can create your beans from anywhere within
  678. your application, using whatever means you think fit (eg <literal>new
  679. Person();</literal>) and they will have the security interceptor
  680. applied.</para>
  681. </sect2>
  682. <sect2 id="security-interception-filterinvocation">
  683. <title>FilterInvocation Security Interceptor</title>
  684. <para>To secure <literal>FilterInvocation</literal>s, developers need
  685. to add a filter to their <literal>web.xml</literal> that delegates to
  686. the <literal>SecurityEnforcementFilter</literal>. A typical
  687. configuration example is provided below: <programlisting>&lt;filter&gt;
  688. &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
  689. &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
  690. &lt;init-param&gt;
  691. &lt;param-name&gt;targetClass&lt;/param-name&gt;
  692. &lt;param-value&gt;net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter&lt;/param-value&gt;
  693. &lt;/init-param&gt;
  694. &lt;/filter&gt;
  695. &lt;filter-mapping&gt;
  696. &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
  697. &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  698. &lt;/filter-mapping&gt;</programlisting></para>
  699. <para>Notice that the filter is actually a
  700. <literal>FilterToBeanProxy</literal>. Most of the filters used by the
  701. Acegi Security System for Spring use this class. Refer to the Filters
  702. section to learn more about this bean.</para>
  703. <para>In the application context you will need to configure three
  704. beans:</para>
  705. <programlisting>&lt;bean id="securityEnforcementFilter" class="net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter"&gt;
  706. &lt;property name="filterSecurityInterceptor"&gt;&lt;ref bean="filterInvocationInterceptor"/&gt;&lt;/property&gt;
  707. &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;
  708. &lt;/bean&gt;
  709. &lt;bean id="authenticationEntryPoint" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
  710. &lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
  711. &lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
  712. &lt;/bean&gt;
  713. &lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
  714. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  715. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  716. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  717. &lt;property name="objectDefinitionSource"&gt;
  718. &lt;value&gt;
  719. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  720. \A/secure/super/.*\Z=ROLE_WE_DONT_HAVE
  721. \A/secure/.*\Z=ROLE_SUPERVISOR,ROLE_TELLER
  722. &lt;/value&gt;
  723. &lt;/property&gt;
  724. &lt;/bean&gt;</programlisting>
  725. <para>The <literal>AuthenticationEntryPoint</literal> will be called
  726. if the user requests a secure HTTP resource but they are not
  727. authenticated. The class handles presenting the appropriate response
  728. to the user so that authentication can begin. Three concrete
  729. implementations are provided with the Acegi Security System for
  730. Spring: <literal>AuthenticationProcessingFilterEntryPoint</literal>
  731. for commencing a form-based authentication,
  732. <literal>BasicProcessingFilterEntryPoint</literal> for commencing a
  733. HTTP Basic authentication process, and
  734. <literal>CasProcessingFilterEntryPoint</literal> for commencing a Yale
  735. Central Authentication Service (CAS) login. The
  736. <literal>AuthenticationProcessingFilterEntryPoint</literal> and
  737. <literal>CasProcessingFilterEntryPoint</literal> have optional
  738. properties related to forcing the use of HTTPS, so please refer to the
  739. JavaDocs if you require this.</para>
  740. <para>The <literal>PortMapper</literal> provides information on which
  741. HTTPS ports correspond to which HTTP ports. This is used by the
  742. <literal>AuthenticationProcessingFilterEntryPoint</literal> and
  743. several other beans. The default implementation,
  744. <literal>PortMapperImpl</literal>, knows the common HTTP ports 80 and
  745. 8080 map to HTTPS ports 443 and 8443 respectively. You can customise
  746. this mapping if desired.</para>
  747. <para>The <literal>SecurityEnforcementFilter</literal> primarily
  748. provides session management support and initiates authentication when
  749. required. It delegates actual <literal>FilterInvocation</literal>
  750. security decisions to the configured
  751. <literal>FilterSecurityInterceptor</literal>.</para>
  752. <para>Like any other security interceptor, the
  753. <literal>FilterSecurityInterceptor</literal> requires a reference to
  754. an <literal>AuthenticationManager</literal>,
  755. <literal>AccessDecisionManager</literal> and
  756. <literal>RunAsManager</literal>, which are each discussed in separate
  757. sections below. The <literal>FilterSecurityInterceptor</literal> is
  758. also configured with configuration attributes that apply to different
  759. HTTP URL requests. A full discussion of configuration attributes is
  760. provided in the High Level Design section of this document.</para>
  761. <para>The <literal>FilterSecurityInterceptor</literal> can be
  762. configured with configuration attributes in two ways. The first is via
  763. a property editor and the application context, which is shown above.
  764. The second is via writing your own
  765. <literal>ObjectDefinitionSource</literal>, although this is beyond the
  766. scope of this document. Irrespective of the approach used, the
  767. <literal>ObjectDefinitionSource</literal> is responsible for returning
  768. a <literal>ConfigAttributeDefinition</literal> object that contains
  769. all of the configuration attributes associated with a single secure
  770. HTTP URL.</para>
  771. <para>It should be noted that the
  772. <literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal>
  773. method actually expects an instance of
  774. <literal>FilterInvocationDefinitionSource</literal>. This is a marker
  775. interface which subclasses <literal>ObjectDefinitionSource</literal>.
  776. It simply denotes the <literal>ObjectDefinitionSource</literal>
  777. understands <literal>FilterInvocation</literal>s. In the interests of
  778. simplicity we'll continue to refer to the
  779. <literal>FilterInvocationDefinitionSource</literal> as an
  780. <literal>ObjectDefinitionSource</literal>, as the distinction is of
  781. little relevance to most users of the
  782. <literal>FilterSecurityInterceptor</literal>.</para>
  783. <para>If using the application context property editor approach (as
  784. shown above), commas are used to delimit the different configuration
  785. attributes that apply to each HTTP URL. Each configuration attribute
  786. is assigned into its own <literal>SecurityConfig</literal> object. The
  787. <literal>SecurityConfig</literal> object is discussed in the High
  788. Level Design section. The <literal>ObjectDefinitionSource</literal>
  789. created by the property editor,
  790. <literal>FilterInvocationDefinitionSource</literal>, matches
  791. configuration attributes against <literal>FilterInvocations</literal>
  792. based on expression evaluation of the request URL. Two standard
  793. expression syntaxes are supported. The default is to treat all
  794. expressions as regular expressions. Alternatively, the presence of a
  795. <literal>PATTERN_TYPE_APACHE_ANT</literal> directive will cause all
  796. expressions to be treated as Apache Ant paths. It is not possible to
  797. mix expression syntaxes within the same definition. For example, the
  798. earlier configuration could be generated using Apache Ant paths as
  799. follows:</para>
  800. <para><programlisting>&lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
  801. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  802. &lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
  803. &lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
  804. &lt;property name="objectDefinitionSource"&gt;
  805. &lt;value&gt;
  806. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  807. PATTERN_TYPE_APACHE_ANT
  808. /secure/super/**=ROLE_WE_DONT_HAVE
  809. /secure/**=ROLE_SUPERVISOR,ROLE_TELLER
  810. &lt;/value&gt;
  811. &lt;/property&gt;
  812. &lt;/bean&gt;</programlisting></para>
  813. <para>Irrespective of the type of expression syntax used, expressions
  814. are always evaluated in the order they are defined. Thus it is
  815. important that more specific expressions are defined higher in the
  816. list than less specific expressions. This is reflected in our example
  817. above, where the more specific <literal>/secure/super/</literal>
  818. pattern appears higher than the less specific
  819. <literal>/secure/</literal> pattern. If they were reversed, the
  820. <literal>/secure/</literal> pattern would always match and the
  821. <literal>/secure/super/</literal> pattern would never be
  822. evaluated.</para>
  823. <para>The special keyword
  824. <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> causes
  825. the <literal>FilterInvocationDefinitionSource</literal> to
  826. automatically convert a request URL to lowercase before comparison
  827. against the expressions. Whilst by default the case of the request URL
  828. is not converted, it is generally recommended to use
  829. <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> and
  830. write each expression assuming lowercase.</para>
  831. <para>As with other security interceptors, the
  832. <literal>validateConfigAttributes</literal> property is observed. When
  833. set to <literal>true</literal> (the default), at startup time the
  834. <literal>FilterSecurityInterceptor</literal> will evaluate if the
  835. provided configuration attributes are valid. It does this by checking
  836. each configuration attribute can be processed by either the
  837. <literal>AccessDecisionManager</literal> or the
  838. <literal>RunAsManager</literal>. If neither of these can process a
  839. given configuration attribute, an exception is thrown.</para>
  840. </sect2>
  841. </sect1>
  842. <sect1 id="security-authentication">
  843. <title>Authentication</title>
  844. <sect2 id="security-authentication-requests">
  845. <title>Authentication Requests</title>
  846. <para>Authentication requires a way for client code to present its
  847. security identification to the Acegi Security System for Spring. This
  848. is the role of the <literal>Authentication</literal> interface. The
  849. <literal>Authentication</literal> interface holds three important
  850. objects: the principal (the identity of the caller), the credentials
  851. (the proof of the identity of the caller, such as a password), and the
  852. authorities that have been granted to the principal. The principal and
  853. its credentials are populated by the client code, whilst the granted
  854. authorities are populated by the
  855. <literal>AuthenticationManager</literal>.</para>
  856. <para><mediaobject>
  857. <imageobject role="html">
  858. <imagedata align="center" fileref="images/Authentication.gif"
  859. format="GIF" />
  860. </imageobject>
  861. <caption>
  862. <para>Figure 3: Key Authentication Architecture</para>
  863. </caption>
  864. </mediaobject></para>
  865. <para>As shown in Figure 3, the Acegi Security System for Spring
  866. includes several concrete <literal>Authentication</literal>
  867. implementations:</para>
  868. <itemizedlist spacing="compact">
  869. <listitem>
  870. <para><literal>UsernamePasswordAuthenticationToken</literal>
  871. allows a username and password to be presented as the principal
  872. and credentials respectively. It is also what is created by the
  873. HTTP Session Authentication system.</para>
  874. </listitem>
  875. <listitem>
  876. <para><literal>TestingAuthenticationToken</literal> facilitates
  877. unit testing by automatically being considered an authenticated
  878. object by its associated
  879. <literal>AuthenticationProvider</literal>.</para>
  880. </listitem>
  881. <listitem>
  882. <para><literal>RunAsUserToken</literal> is used by the default
  883. run-as authentication replacement implementation. This is
  884. discussed further in the Run-As Authentication Replacement
  885. section.</para>
  886. </listitem>
  887. <listitem>
  888. <para><literal>CasAuthenticationToken</literal> is used to
  889. represent a successful Yale Central Authentication Service (CAS)
  890. authentication. This is discussed further in the CAS
  891. section.</para>
  892. </listitem>
  893. <listitem>
  894. <para><literal>PrincipalAcegiUserToken</literal> and
  895. <literal>JettyAcegiUserToken</literal> implement
  896. <literal>AuthByAdapter</literal> (a subclass of
  897. <literal>Authentication</literal>) and are used whenever
  898. authentication is completed by Acegi Security System for Spring
  899. container adapters. This is discussed further in the Container
  900. Adapters section.</para>
  901. </listitem>
  902. </itemizedlist>
  903. <para>The authorities granted to a principal are represented by the
  904. <literal>GrantedAuthority</literal> interface. The
  905. <literal>GrantedAuthority</literal> interface is discussed at length
  906. in the Authorization section.</para>
  907. </sect2>
  908. <sect2 id="security-authentication-manager">
  909. <title>Authentication Manager</title>
  910. <para>As discussed in the Security Interception section, the
  911. <literal>AbstractSecurityInterceptor</literal> extracts the
  912. <literal>Authentication</literal> object from the
  913. <literal>SecureContext</literal> in the
  914. <literal>ContextHolder</literal>. This is then passed to an
  915. <literal>AuthenticationManager</literal>. The
  916. <literal>AuthenticationManager</literal> interface is very
  917. simple:</para>
  918. <programlisting>public Authentication authenticate(Authentication authentication) throws AuthenticationException;</programlisting>
  919. <para>Implementations of <literal>AuthenticationManager</literal> are
  920. required to throw an <literal>AuthenticationException</literal> should
  921. authentication fail, or return a fully populated
  922. <literal>Authentication</literal> object. In particular, the returned
  923. <literal>Authentication</literal> object should contain an array of
  924. <literal>GrantedAuthority</literal> objects. The
  925. <literal>SecurityInterceptor</literal> places the populated
  926. <literal>Authentication</literal> object back in the
  927. <literal>SecureContext</literal> in the
  928. <literal>ContextHolder</literal>, overwriting the original
  929. <literal>Authentication</literal> object.</para>
  930. <para>The <literal>AuthenticationException</literal> has a number of
  931. subclasses. The most important are
  932. <literal>BadCredentialsException</literal> (an incorrect principal or
  933. credentials), <literal>DisabledException</literal> and
  934. <literal>LockedException</literal>. The latter two exceptions indicate
  935. the principal was found, but the credentials were not checked and
  936. authentication is denied. An
  937. <literal>AuthenticationServiceException</literal> is also provided,
  938. which indicates the authentication system could not process the
  939. request (eg a database was unavailable).
  940. <literal>AuthenticationException</literal> also has a
  941. <literal>CredentialsExpiredException</literal> and
  942. <literal>AccoungtExpiredException</literal> subclass, although these
  943. are less commonly used.</para>
  944. </sect2>
  945. <sect2 id="security-authentication-provider">
  946. <title>Provider-Based Authentication</title>
  947. <para>Whilst the basic <literal>Authentication</literal> and
  948. <literal>AuthenticationManager</literal> interfaces enable users to
  949. develop their own authentication systems, users should consider using
  950. the provider-based authentication packages provided by the Acegi
  951. Security System for Spring. The key class,
  952. <literal>ProviderManager</literal>, is configured via the bean context
  953. with a list of <literal>AuthenticationProvider</literal>s:</para>
  954. <para><programlisting>&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
  955. &lt;property name="providers"&gt;
  956. &lt;list&gt;
  957. &lt;ref bean="daoAuthenticationProvider"/&gt;
  958. &lt;ref bean="someOtherAuthenticationProvider"/&gt;
  959. &lt;/list&gt;
  960. &lt;/property&gt;
  961. &lt;/bean&gt;</programlisting></para>
  962. <para><literal>ProviderManager</literal> calls a series of registered
  963. <literal>AuthenticationProvider</literal> implementations, until one
  964. is found that indicates it is able to authenticate a given
  965. <literal>Authentication</literal> class. When the first compatible
  966. <literal>AuthenticationProvider</literal> is located, it is passed the
  967. authentication request. The <literal>AuthenticationProvider</literal>
  968. will then either throw an <literal>AuthenticationException</literal>
  969. or return a fully populated <literal>Authentication</literal>
  970. object.</para>
  971. <para>Note the <literal>ProviderManager</literal> may throw a
  972. <literal>ProviderNotFoundException</literal> (a subclass of
  973. <literal>AuthenticationException</literal>) if it none of the
  974. registered <literal>AuthenticationProviders</literal> can validate the
  975. <literal>Authentication</literal> object.</para>
  976. <para>Several <literal>AuthenticationProvider</literal>
  977. implementations are provided with the Acegi Security System for
  978. Spring:</para>
  979. <para><itemizedlist spacing="compact">
  980. <listitem>
  981. <para><literal>TestingAuthenticationProvider</literal> is able
  982. to authenticate a <literal>TestingAuthenticationToken</literal>.
  983. The limit of its authentication is simply to treat whatever is
  984. contained in the <literal>TestingAuthenticationToken</literal>
  985. as valid. This makes it ideal for use during unit testing, as
  986. you can create an <literal>Authentication</literal> object with
  987. precisely the <literal>GrantedAuthority</literal> objects
  988. required for calling a given method. You definitely would not
  989. register this <literal>AuthenticationProvider</literal> on a
  990. production system.</para>
  991. </listitem>
  992. <listitem>
  993. <para><literal>DaoAuthenticationProvider</literal> is able to
  994. authenticate a
  995. <literal>UsernamePasswordAuthenticationToken</literal> by
  996. accessing an authentication respository via a data access
  997. object. This is discussed further below, as it is the main way
  998. authentication is initially handled.</para>
  999. </listitem>
  1000. <listitem>
  1001. <para><literal>RunAsImplAuthenticationProvider</literal> is able
  1002. to authenticate a <literal>RunAsUserToken</literal>. This is
  1003. discussed further in the Run-As Authentication Replacement
  1004. section. You would not register this
  1005. <literal>AuthenticationProvider</literal> if you were not using
  1006. run-as replacement.</para>
  1007. </listitem>
  1008. <listitem>
  1009. <para><literal>AuthByAdapterProvider</literal> is able to
  1010. authenticate any <literal>AuthByAdapter</literal> (a subclass of
  1011. <literal>Authentication</literal> used with container adapters).
  1012. This is discussed further in the Container Adapters section. You
  1013. would not register this
  1014. <literal>AuthenticationProvider</literal> if you were not using
  1015. container adapters.</para>
  1016. </listitem>
  1017. <listitem>
  1018. <para><literal>CasAuthenticationProvider</literal> is able to
  1019. authenticate Yale Central Authentication Service (CAS) tickets.
  1020. This is discussed further in the CAS Single Sign On
  1021. section.</para>
  1022. </listitem>
  1023. <listitem>
  1024. <para><literal>JaasAuthenticationProvider</literal> is able to
  1025. delegate authentication requests to a JAAS
  1026. <literal>LoginModule</literal>. This is discussed further
  1027. below.</para>
  1028. </listitem>
  1029. </itemizedlist></para>
  1030. </sect2>
  1031. <sect2 id="security-authentication-provider-dao">
  1032. <title>Data Access Object Authentication Provider</title>
  1033. <para>The Acegi Security System for Spring includes a
  1034. production-quality <literal>AuthenticationProvider</literal>
  1035. implementation called <literal>DaoAuthenticationProvider</literal>.
  1036. This authentication provider is able to authenticate a
  1037. <literal>UsernamePasswordAuthenticationToken</literal> by obtaining
  1038. authentication details from a data access object configured at bean
  1039. creation time:</para>
  1040. <para><programlisting>&lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
  1041. &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
  1042. &lt;property name="saltSource"&gt;&lt;ref bean="saltSource"/&gt;&lt;/property&gt;
  1043. &lt;property name="passwordEncoder"&gt;&lt;ref bean="passwordEncoder"/&gt;&lt;/property&gt;
  1044. &lt;/bean&gt;</programlisting></para>
  1045. <para>The <literal>PasswordEncoder</literal> and
  1046. <literal>SaltSource</literal> are optional. A
  1047. <literal>PasswordEncoder</literal> provides encoding and decoding of
  1048. passwords obtained from the authentication repository. A
  1049. <literal>SaltSource</literal> enables the passwords to be populated
  1050. with a "salt", which enhances the security of the passwords in the
  1051. authentication repository. <literal>PasswordEncoder</literal>
  1052. implementations are provided with the Acegi Security System for Spring
  1053. covering MD5, SHA and cleartext encodings. Two
  1054. <literal>SaltSource</literal> implementations are also provided:
  1055. <literal>SystemWideSaltSource</literal> which encodes all passwords
  1056. with the same salt, and <literal>ReflectionSaltSource</literal>, which
  1057. inspects a given property of the returned
  1058. <literal>UserDetails</literal> object to obtain the salt. Please refer
  1059. to the JavaDocs for further details on these optional features.</para>
  1060. <para>In addition to the properties above, the
  1061. <literal>DaoAuthenticationProvider</literal> supports optional caching
  1062. of <literal>UserDetails</literal> objects. The
  1063. <literal>UserCache</literal> interface enables the
  1064. <literal>DaoAuthenticationProvider</literal> to place a
  1065. <literal>UserDetails</literal> object into the cache, and retrieve it
  1066. from the cache upon subsequent authentication attempts for the same
  1067. username. By default the <literal>DaoAuthenticationProvider</literal>
  1068. uses the <literal>NullUserCache</literal>, which performs no caching.
  1069. A usable caching implementation is also provided,
  1070. <literal>EhCacheBasedUserCache</literal>, which is configured as
  1071. follows:</para>
  1072. <para><programlisting>&lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
  1073. &lt;property name="authenticationDao"&gt;&lt;ref bean="authenticationDao"/&gt;&lt;/property&gt;
  1074. &lt;property name="userCache"&gt;&lt;ref bean="userCache"/&gt;&lt;/property&gt;
  1075. &lt;/bean&gt;
  1076. &lt;bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"&gt;
  1077. &lt;property name="configLocation"&gt;
  1078. &lt;value&gt;classpath:/ehcache-failsafe.xml&lt;/value&gt;
  1079. &lt;/property&gt;
  1080. &lt;/bean&gt;
  1081. &lt;bean id="userCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean"&gt;
  1082. &lt;property name="cacheManager"&gt;
  1083. &lt;ref local="cacheManager"/&gt;
  1084. &lt;/property&gt;
  1085. &lt;property name="cacheName"&gt;
  1086. &lt;value&gt;userCache&lt;/value&gt;
  1087. &lt;/property&gt;
  1088. &lt;/bean&gt;
  1089. &lt;bean id="userCache" class="net.sf.acegisecurity.providers.dao.cache.EhCacheBasedUserCache"&gt;
  1090. &lt;property name="cache"&gt;&lt;ref local="userCacheBackend"/&gt;&lt;/property&gt;
  1091. &lt;/bean&gt;</programlisting></para>
  1092. <para>All Acegi Security EH-CACHE implementations (including
  1093. <literal>EhCacheBasedUserCache</literal>) require an EH-CACHE
  1094. <literal>Cache</literal> object. The <literal>Cache</literal> object
  1095. can be obtained from wherever you like, although we recommend you use
  1096. Spring's factory classes as shown in the above configuration. If using
  1097. Spring's factory classes, please refer to the Spring documentation for
  1098. further details on how to optimise the cache storage location, memory
  1099. usage, eviction policies, timeouts etc.</para>
  1100. <para>For a class to be able to provide the
  1101. <literal>DaoAuthenticationProvider</literal> with access to an
  1102. authentication repository, it must implement the
  1103. <literal>AuthenticationDao</literal> interface:</para>
  1104. <para><programlisting>public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;</programlisting></para>
  1105. <para>The <literal>UserDetails</literal> is an interface that provides
  1106. getters that guarantee non-null provision of basic authentication
  1107. information such as the username, password, granted authorities and
  1108. whether the user is enabled or disabled. A concrete implementation,
  1109. <literal>User</literal>, is also provided. Acegi Security users will
  1110. need to decide when writing their <literal>AuthenticationDao</literal>
  1111. what type of <literal>UserDetails</literal> to return. In most cases
  1112. <literal>User</literal> will be used directly or subclassed, although
  1113. special circumstances (such as object relational mappers) may require
  1114. users to write their own <literal>UserDetails</literal> implementation
  1115. from scratch. <literal>UserDetails</literal> is often used to store
  1116. additional principal-related properties (such as their telephone
  1117. number and email address), so they can be easily used by web
  1118. views.</para>
  1119. <para>Given <literal>AuthenticationDao</literal> is so simple to
  1120. implement, it should be easy for users to retrieve authentication
  1121. information using a persistence strategy of their choice.</para>
  1122. <para>A design decision was made not to support account locking in the
  1123. <literal>DaoAuthenticationProvider</literal>, as doing so would have
  1124. increased the complexity of the <literal>AuthenticationDao</literal>
  1125. interface. For instance, a method would be required to increase the
  1126. count of unsuccessful authentication attempts. Such functionality
  1127. could be easily provided by leveraging the application event
  1128. publishing features discussed below.</para>
  1129. <para><literal>DaoAuthenticationProvider</literal> returns an
  1130. <literal>Authentication</literal> object which in turn has its
  1131. <literal>principal</literal> property set. The principal will be
  1132. either a <literal>String</literal> (which is essentially the username)
  1133. or a <literal>UserDetails</literal> object (which was looked up from
  1134. the <literal>AuthenticationDao</literal>). By default the
  1135. <literal>UserDetails</literal> is returned, as this enables
  1136. applications to add extra properties potentially of use in
  1137. applications, such as the user's full name, email address etc. If
  1138. using container adapters, or if your applications were written to
  1139. operate with <literal>String</literal>s (as was the case for releases
  1140. prior to Acegi Security 0.6), you should set the
  1141. <literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
  1142. property to <literal>true</literal> in your application
  1143. context.</para>
  1144. </sect2>
  1145. <sect2 id="security-authentication-provider-events">
  1146. <title>Event Publishing</title>
  1147. <para>The <literal>DaoAuthenticationProvider</literal> automatically
  1148. obtains the <literal>ApplicationContext</literal> it is running in at
  1149. startup time. This allows the provider to publish events through the
  1150. standard Spring event framework. Three types of event messages are
  1151. published:</para>
  1152. <itemizedlist spacing="compact">
  1153. <listitem>
  1154. <para><literal>AuthenticationSuccessEvent</literal> is published
  1155. when an authentication request is successful.</para>
  1156. </listitem>
  1157. <listitem>
  1158. <para><literal>AuthenticationFailureDisabledEvent</literal> is
  1159. published when an authentication request is unsuccessful because
  1160. the returned <literal>UserDetails</literal> is disabled. This is
  1161. normally the case when an account is locked.</para>
  1162. </listitem>
  1163. <listitem>
  1164. <para><literal>AuthenticationFailureAccountExpiredEvent</literal>
  1165. is published when an authentication request is unsuccessful
  1166. because the returned <literal>UserDetails</literal> indicates the
  1167. account has expired. Some applications may wish to distinguish
  1168. between an account being disabled and expired.</para>
  1169. </listitem>
  1170. <listitem>
  1171. <para><literal>AuthenticationFailureCredentialsExpiredEvent</literal>
  1172. is published when an authentication request is unsuccessful
  1173. because the returned <literal>UserDetails</literal> indicates the
  1174. account's credentials have expired. Some applications may wish to
  1175. expire the credentials if, for example, a password is not changed
  1176. with sufficient regularity.</para>
  1177. </listitem>
  1178. <listitem>
  1179. <para><literal>AuthenticationFailureUsernameNotFoundEvent</literal>
  1180. is published when an authentication request is unsuccessful
  1181. because the <literal>AuthenticationDao</literal> could not locate
  1182. the <literal>UserDetails</literal>.</para>
  1183. </listitem>
  1184. <listitem>
  1185. <para><literal>AuthenticationFailurePasswordEvent</literal> is
  1186. published when an authentication request is unsuccessful because
  1187. the presented password did not match that in the
  1188. <literal>UserDetails</literal>.</para>
  1189. </listitem>
  1190. </itemizedlist>
  1191. <para>Each event contains two objects: the
  1192. <literal>Authentication</literal> object that represented the
  1193. authentication request, and the <literal>UserDetails</literal> object
  1194. that was found in response to the authentication request (clearly the
  1195. latter will be a dummy object in the case of
  1196. <literal>AuthenticationFailureUsernameNotFoundEvent</literal>). The
  1197. <literal>Authentication</literal> interface provides a
  1198. <literal>getDetails()</literal> method which often includes
  1199. information that event consumers may find useful (eg the TCP/IP
  1200. address that the authentication request originated from).</para>
  1201. <para>As per standard Spring event handling, you can receive these
  1202. events by adding a bean to the application context which implements
  1203. the <literal>ApplicationListener</literal> interface. Included with
  1204. Acegi Security is a <literal>LoggerListener</literal> class which
  1205. receives these events and publishes their details to Commons Logging.
  1206. Refer to the JavaDocs for <literal>LoggerListener</literal> for
  1207. details on the logging priorities used for different message
  1208. types.</para>
  1209. <para>This event publishing system enables you to implement account
  1210. locking and record authentication event history. This might be of
  1211. interest to application users, who can be advised of the times and
  1212. source IP address of all unsuccessful password attempts (and account
  1213. lockouts) since their last successful login. Such capabilities are
  1214. simple to implement and greatly improve the security of your
  1215. application.</para>
  1216. </sect2>
  1217. <sect2 id="security-authentication-provider-in-memory">
  1218. <title>In-Memory Authentication</title>
  1219. <para>Whilst it is easy to use the
  1220. <literal>DaoAuthenticationProvider</literal> and create a custom
  1221. <literal>AuthenticationDao</literal> implementation that extracts
  1222. information from a persistence engine of choice, many applications do
  1223. not require such complexity. One alternative is to configure an
  1224. authentication repository in the application context itself using the
  1225. <literal>InMemoryDaoImpl</literal>:</para>
  1226. <para><programlisting>&lt;bean id="inMemoryDaoImpl" class="net.sf.acegisecurity.providers.dao.memory.InMemoryDaoImpl"&gt;
  1227. &lt;property name="userMap"&gt;
  1228. &lt;value&gt;
  1229. marissa=koala,ROLE_TELLER,ROLE_SUPERVISOR
  1230. dianne=emu,ROLE_TELLER
  1231. scott=wombat,ROLE_TELLER
  1232. peter=opal,disabled,ROLE_TELLER
  1233. &lt;/value&gt;
  1234. &lt;/property&gt;
  1235. &lt;/bean&gt;</programlisting></para>
  1236. <para>The <literal>userMap</literal> property contains each of the
  1237. usernames, passwords, a list of granted authorities and an optional
  1238. enabled/disabled keyword. Commas delimit each token. The username must
  1239. appear to the left of the equals sign, and the password must be the
  1240. first token to the right of the equals sign. The
  1241. <literal>enabled</literal> and <literal>disabled</literal> keywords
  1242. (case insensitive) may appear in the second or any subsequent token.
  1243. Any remaining tokens are treated as granted authorities, which are
  1244. created as <literal>GrantedAuthorityImpl</literal> objects (refer to
  1245. the Authorization section for further discussion on granted
  1246. authorities). Note that if a user has no password and/or no granted
  1247. authorities, the user will not be created in the in-memory
  1248. authentication repository.</para>
  1249. </sect2>
  1250. <sect2 id="security-authentication-provider-jdbc">
  1251. <title>JDBC Authentication</title>
  1252. <para>The Acegi Security System for Spring also includes an
  1253. authentication provider that can obtain authentication information
  1254. from a JDBC data source. The typical configuration for the
  1255. <literal>JdbcDaoImpl</literal> is shown below:</para>
  1256. <para><programlisting>&lt;bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"&gt;
  1257. &lt;property name="driverClassName"&gt;&lt;value&gt;org.hsqldb.jdbcDriver&lt;/value&gt;&lt;/property&gt;
  1258. &lt;property name="url"&gt;&lt;value&gt;jdbc:hsqldb:hsql://localhost:9001&lt;/value&gt;&lt;/property&gt;
  1259. &lt;property name="username"&gt;&lt;value&gt;sa&lt;/value&gt;&lt;/property&gt;
  1260. &lt;property name="password"&gt;&lt;value&gt;&lt;/value&gt;&lt;/property&gt;
  1261. &lt;/bean&gt;
  1262. &lt;bean id="jdbcDaoImpl" class="net.sf.acegisecurity.providers.dao.jdbc.JdbcDaoImpl"&gt;
  1263. &lt;property name="dataSource"&gt;&lt;ref bean="dataSource"/&gt;&lt;/property&gt;
  1264. &lt;/bean&gt;</programlisting></para>
  1265. <para>You can use different relational database management systems by
  1266. modifying the <literal>DriverManagerDataSource</literal> shown above.
  1267. Irrespective of the database used, a standard schema must be used as
  1268. indicated in <literal>dbinit.txt</literal>.</para>
  1269. <para>If you default schema is unsuitable for your needs,
  1270. <literal>JdbcDaoImpl</literal> provides two properties that allow
  1271. customisation of the SQL statements. You may also subclass the
  1272. <literal>JdbcDaoImpl</literal> if further customisation is necessary.
  1273. Please refer to the JavaDocs for details.</para>
  1274. <para>The Acegi Security System for Spring ships with a Hypersonic SQL
  1275. instance that has the required authentication information and sample
  1276. data already populated. To use this server, simply execute the
  1277. <literal>server.bat</literal> or <literal>server.sh</literal> script
  1278. included in the distribution. This will load a new database server
  1279. instance that will service requests made to the URL indicated in the
  1280. bean context configuration shown above.</para>
  1281. </sect2>
  1282. <sect2 id="security-authentication-concurrent-login">
  1283. <title>Concurrent Session Support</title>
  1284. <para>Acegi Security is able to stop the same principal authenticating
  1285. to the same web application multiple times concurrently. Put
  1286. differently, you can stop user "Batman" from logging into a web
  1287. application twice at the same time.</para>
  1288. <para>To use concurrent session support, you'll need to add the
  1289. following to web.xml:</para>
  1290. <para><programlisting>&lt;listener&gt;
  1291. &lt;listener-class&gt;net.sf.acegisecurity.ui.session.HttpSessionEventPublisher&lt;/listener-class&gt;
  1292. &lt;/listener&gt;</programlisting></para>
  1293. <para>The above code causes an <literal>ApplicationEvent</literal> to
  1294. be published to the Spring <literal>ApplicationContext</literal> every
  1295. time a <literal>HttpSession</literal> commences or terminates. This is
  1296. critical, as it allows the
  1297. <literal>ConcurrentSessionControllerImpl</literal> to be notified when
  1298. a session ends. Next up you'll need to wire the
  1299. <literal>ConcurrentSessionControllerImpl</literal> into your existing
  1300. <literal>ProviderManager</literal>:</para>
  1301. <para><programlisting>&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
  1302. &lt;property name="providers"&gt;
  1303. &lt;!-- your providers go here --&gt;
  1304. &lt;/property&gt;
  1305. &lt;property name="sessionController"&gt;&lt;ref bean="concurrentSessionController"/&gt;&lt;/property&gt;
  1306. &lt;/bean&gt;
  1307. &lt;bean id="concurrentSessionController" class="net.sf.acegisecurity.providers.ConcurrentSessionControllerImpl"&gt;
  1308. &lt;property name="maxSessions"&gt;&lt;value&gt;1&lt;/value&gt;&lt;/property&gt;
  1309. &lt;/bean&gt;</programlisting></para>
  1310. <para>Ensure you do not in-line the
  1311. <literal>ConcurrentSessionControllerImpl</literal> when declaring it
  1312. in your XML. This is important, as it appears that in-lined bean
  1313. declarations do not receive ApplicationEvents.</para>
  1314. <para>The <literal>ConcurrentSessionControllerImpl</literal> relies
  1315. heavily on the
  1316. <literal>Authentication.getPrincipal().equals()</literal> method. If
  1317. you are using a custom <literal>Authentication</literal> object,
  1318. please keep this in mind. In order for the
  1319. <literal>ConcurrentSessionControllerImpl</literal> to release a given
  1320. <literal>HttpSession</literal>, and thus let the user log in to a new
  1321. <literal>HttpSession</literal>, the existing
  1322. <literal>HttpSession</literal> must be invalidated. For example, if
  1323. "Batman" logs into the web application, checks for crimes being
  1324. commited, and the just closes his browser with out "logging out", he
  1325. will not be able to log back in until his
  1326. <literal>HttpSession</literal> is timed out by the server (and a
  1327. corresponding <literal>ApplicationEvent</literal> is published via
  1328. <literal>HttpSessionEventPublisher</literal> to the
  1329. <literal>ConcurrentSessionControllerImpl</literal>). You would have to
  1330. look at your container's documentation to determine the default
  1331. timeout period. You can also configure the session timeout in your
  1332. <literal>web.xml</literal>:<programlisting>&lt;session-config&gt;
  1333. &lt;session-timeout&gt;30&lt;/session-timeout&gt;
  1334. &lt;/session-config&gt;</programlisting></para>
  1335. </sect2>
  1336. <sect2 id="security-authentication-provider-jaas">
  1337. <title>JAAS Authentication</title>
  1338. <para>Acegi Security provides a package able to delegate
  1339. authentication requests to the Java Authentication and Authorization
  1340. Service (JAAS). This package is discussed in detail below.</para>
  1341. <para>Central to JAAS operation are login configuration files. To
  1342. learn more about JAAS login configuration files, consult the JAAS
  1343. reference documentation available from Sun Microsystems. We expect you
  1344. to have a basic understanding of JAAS and its login configuration file
  1345. syntax in order to understand this section.</para>
  1346. <sect3>
  1347. <title>JaasAuthenticationProvider</title>
  1348. <para>The <literal>JaasAuthenticationProvider</literal> attempts to
  1349. authenticate a user’s principal and credentials through JAAS.</para>
  1350. <para>Let’s assume we have a JAAS login configuration file,
  1351. <literal>/WEB-INF/login.conf</literal>, with the following
  1352. contents:</para>
  1353. <para><programlisting>JAASTest {
  1354. sample.SampleLoginModule required;
  1355. };</programlisting></para>
  1356. <para>Like all Acegi Security beans, the
  1357. <literal>JaasAuthenticationProvider</literal> is configured via the
  1358. application context. The following definitions would correspond to
  1359. the above JAAS login configuration file:</para>
  1360. <para><programlisting>&lt;bean id="jaasAuthenticationProvider" class="net.sf.acegisecurity.providers.jaas.JaasAuthenticationProvider"&gt;
  1361. &lt;property name="loginConfig"&gt;
  1362. &lt;value&gt;/WEB-INF/login.conf&lt;/value&gt;
  1363. &lt;/property&gt;
  1364. &lt;property name="loginContextName"&gt;
  1365. &lt;value&gt;JAASTest&lt;/value&gt;
  1366. &lt;/property&gt;
  1367. &lt;property name="callbackHandlers"&gt;
  1368. &lt;list&gt;
  1369. &lt;bean class="net.sf.acegisecurity.providers.jaas.JaasNameCallbackHandler"/&gt;
  1370. &lt;bean class="net.sf.acegisecurity.providers.jaas.JaasPasswordCallbackHandler"/&gt;
  1371. &lt;/list&gt;
  1372. &lt;/property&gt;
  1373. &lt;property name="authorityGranters"&gt;
  1374. &lt;list&gt;
  1375. &lt;bean class="net.sf.acegisecurity.providers.jaas.TestAuthorityGranter"/&gt;
  1376. &lt;/list&gt;
  1377. &lt;/property&gt;
  1378. &lt;/bean&gt;</programlisting></para>
  1379. <para>The <literal>CallbackHandler</literal>s and
  1380. <literal>AuthorityGranter</literal>s are discussed below.</para>
  1381. </sect3>
  1382. <sect3>
  1383. <title>Callbacks</title>
  1384. <para>Most JAAS <literal>LoginModule</literal>s require a callback
  1385. of some sort. These callbacks are usually used to obtain the
  1386. username and password from the user. In an Acegi Security
  1387. deployment, Acegi Security is responsible for this user interaction
  1388. (typically via a reference to a
  1389. <literal>ContextHolder</literal>-managed
  1390. <literal>Authentication</literal> object). The JAAS package for
  1391. Acegi Security provides two default callback handlers,
  1392. <literal>JaasNameCallbackHandler</literal> and
  1393. <literal>JaasPasswordCallbackHandler</literal>. Each of these
  1394. callback handlers implement
  1395. <literal>JaasAuthenticationCallbackHandler</literal>. In most cases
  1396. these callback handlers can simply be used without understanding the
  1397. internal mechanics. For those needing full control over the callback
  1398. behavior, internally <literal>JaasAutheticationProvider</literal>
  1399. wraps these <literal>JaasAuthenticationCallbackHandler</literal>s
  1400. with an <literal>InternalCallbackHandler</literal>. The
  1401. <literal>InternalCallbackHandler</literal> is the class that
  1402. actually implements JAAS’ normal <literal>CallbackHandler</literal>
  1403. interface. Any time that the JAAS <literal>LoginModule</literal> is
  1404. used, it is passed a list of application context configured
  1405. <literal>InternalCallbackHandler</literal>s. If the
  1406. <literal>LoginModule</literal> requests a callback against the
  1407. <literal>InternalCallbackHandler</literal>s, the callback is in-turn
  1408. passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
  1409. being wrapped.</para>
  1410. </sect3>
  1411. <sect3>
  1412. <title>AuthorityGranters</title>
  1413. <para>JAAS works with principals. Even “roles” are represented as
  1414. principals in JAAS. Acegi Security, on the other hand, works with
  1415. <literal>Authentication</literal> objects. Each
  1416. <literal>Authentication</literal> object contains a single
  1417. principal, and multiple <literal>GrantedAuthority</literal>[]s. To
  1418. facilitate mapping between these different concepts, the Acegi
  1419. Security JAAS package includes an
  1420. <literal>AuthorityGranter</literal> interface. An
  1421. <literal>AuthorityGranter</literal> is responsible for inspecting a
  1422. JAAS principal and returning a <literal>String</literal>. The
  1423. <literal>JaasAuthenticationProvider</literal> then creates a
  1424. <literal>JaasGrantedAuthority</literal> (which implements Acegi
  1425. Security’s <literal>GrantedAuthority</literal> interface) containing
  1426. both the <literal>AuthorityGranter</literal>-returned
  1427. <literal>String</literal> and the JAAS principal that the
  1428. <literal>AuthorityGranter</literal> was passed. The
  1429. <literal>JaasAuthenticationProvider</literal> obtains the JAAS
  1430. principals by firstly successfully authenticating the user’s
  1431. credentials using the JAAS <literal>LoginModule</literal>, and then
  1432. accessing the <literal>LoginContext</literal> it returns. A call to
  1433. <literal>LoginContext.getSubject().getPrincipals()</literal> is
  1434. made, with each resulting principal passed to each
  1435. <literal>AuthorityGranter</literal> defined against the
  1436. <literal>JaasAuthenticationProvider.setAuthorityGranters(List)</literal>
  1437. property. Acegi Security does not include any production
  1438. <literal>AuthorityGranter</literal>s given every JAAS principal has
  1439. an implementation-specific meaning. However, there is a
  1440. <literal>TestAuthorityGranter</literal> in the unit tests that
  1441. demonstrates a simple <literal>AuthorityGranter</literal>
  1442. implementation.</para>
  1443. </sect3>
  1444. </sect2>
  1445. <sect2 id="security-authentication-provider-siteminder">
  1446. <title>Siteminder Authentication</title>
  1447. <para>Acegi Security provides a web filter that can be used to process
  1448. requests that have been pre-authenticated using Computer
  1449. Associates'/Netegrity's Siteminder product. Acegi's support assumes
  1450. that you're using Siteminder for <emphasis>authentication</emphasis>,
  1451. and your application (or backing datasource) is used for
  1452. <emphasis>authorization</emphasis>. The use of Siteminder for
  1453. <emphasis>authorization</emphasis> is not yet directly
  1454. supported.</para>
  1455. <para>A Siteminder agent is typically set up on your web server to
  1456. intercept a user's first call to your application. This agent
  1457. redirects the user's initial request to a login page, and only after
  1458. successful authentication does your application receive the request.
  1459. Authenticated requests contain one or more HTTP headers populated by
  1460. the Siteminder agent. Below we'll assume that the primary request
  1461. header key is "SM_USER", but keep in mind that your organization's
  1462. header values may be different. Refer to your company's "single
  1463. sign-on" group for details.</para>
  1464. <sect3>
  1465. <title>SiteminderAuthenticationProcessingFilter</title>
  1466. <para>As mentioned above the
  1467. <literal>net.sf.acegisecurity.ui.webapp.SiteminderAuthenticationProcessingFilter</literal>
  1468. attempts to identify a user based on specified HTTP headers.</para>
  1469. <para>The first step is to define our
  1470. <literal>authenticationProcessingFilter</literal> bean and tell it
  1471. what <literal>authenticationManager</literal> to use, where to send
  1472. users upon success and failure and where to find the Siteminder
  1473. username and password values. Most people won't need the password
  1474. value since Siteminder has already authenticated the user, so it's
  1475. OK to use the same username header.</para>
  1476. <para><programlisting> &lt;bean id="authenticationProcessingFilter" class="net.sf.acegisecurity.ui.webapp.SiteminderAuthenticationProcessingFilter"&gt;
  1477. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  1478. &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/login.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
  1479. &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/security.do?method=getMainMenu&lt;/value&gt;&lt;/property&gt;
  1480. &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_acegi_security_check&lt;/value&gt;&lt;/property&gt;
  1481. &lt;property name="siteminderUsernameHeaderKey"&gt;&lt;value&gt;SM_USER&lt;/value&gt;&lt;/property&gt;
  1482. &lt;property name="siteminderPasswordHeaderKey"&gt;&lt;value&gt;SM_USER&lt;/value&gt;&lt;/property&gt;
  1483. &lt;/bean&gt;</programlisting></para>
  1484. <para>Since this <literal>authenticationProcessingFilter</literal>
  1485. depends on an <literal>authenticationManager</literal>, we'll need
  1486. to define one:</para>
  1487. <para><programlisting> &lt;!-- ======================== AUTHENTICATION ======================= --&gt;
  1488. &lt;!--
  1489. - The top-level Authentication Manager is responsible for all application AUTHENTICATION
  1490. - operations. Note that it must reference one or more provider(s) defined below.
  1491. --&gt;
  1492. &lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
  1493. &lt;property name="providers"&gt;
  1494. &lt;list&gt;
  1495. &lt;ref local="daoAuthenticationProvider"/&gt;
  1496. &lt;/list&gt;
  1497. &lt;/property&gt;
  1498. &lt;/bean&gt;</programlisting></para>
  1499. <para>Note that your <literal>daoAuthenticationProvider</literal>
  1500. above will expect the password property to match what it expects.
  1501. Since authentication has already been handled by Siteminder and
  1502. you've specified the same HTTP header for both username and
  1503. password, <literal>daoAuthenticationProvider</literal> can simply
  1504. make sure the username and password values match.</para>
  1505. <para>Finally we need to tell the
  1506. <literal>filterChainProxy</literal> to include
  1507. <literal>authenticationProcessingFilter</literal> in its
  1508. operations.</para>
  1509. <para><programlisting> &lt;!-- ======================== FILTER CHAIN ======================= --&gt;
  1510. &lt;!--
  1511. - The web.xml file has a single filter reference to this top-level bean, which
  1512. - invokes the chain of sub-filters specified below.
  1513. --&gt;
  1514. &lt;bean id="filterChainProxy" class="net.sf.acegisecurity.util.FilterChainProxy"&gt;
  1515. &lt;property name="filterInvocationDefinitionSource"&gt;
  1516. &lt;value&gt;
  1517. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  1518. PATTERN_TYPE_APACHE_ANT
  1519. /**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityEnforcementFilter
  1520. &lt;/value&gt;
  1521. &lt;/property&gt;
  1522. &lt;/bean&gt;</programlisting></para>
  1523. </sect3>
  1524. </sect2>
  1525. <sect2 id="security-authentication-recommendations">
  1526. <title>Authentication Recommendations</title>
  1527. <para>With the heavy use of interfaces throughout the authentication
  1528. system (<literal>Authentication</literal>,
  1529. <literal>AuthenticationManager</literal>,
  1530. <literal>AuthenticationProvider</literal> and
  1531. <literal>AuthenticationDao</literal>) it might be confusing to a new
  1532. user to know which part of the authentication system to customize. In
  1533. general, the following is recommended:</para>
  1534. <itemizedlist>
  1535. <listitem>
  1536. <para>Use the
  1537. <literal>UsernamePasswordAuthenticationToken</literal>
  1538. implementation where possible.</para>
  1539. </listitem>
  1540. <listitem>
  1541. <para>If you simply need to implement a new authentication
  1542. repository (eg to obtain user details from your application’s
  1543. existing database), use the
  1544. <literal>DaoAuthenticationProvider</literal> along with the
  1545. <literal>AuthenticationDao</literal>. It is the fastest and safest
  1546. way to integrate an external database.</para>
  1547. </listitem>
  1548. <listitem>
  1549. <para>If you're using Container Adapters or a
  1550. <literal>RunAsManager</literal> that replaces the
  1551. <literal>Authentication</literal> object, ensure you have
  1552. registered the <literal>AuthByAdapterProvider</literal> and
  1553. <literal>RunAsManagerImplProvider</literal> respectively with your
  1554. <literal>ProviderManager</literal>.</para>
  1555. </listitem>
  1556. <listitem>
  1557. <para>Never enable the
  1558. <literal>TestingAuthenticationProvider</literal> on a production
  1559. system. Doing so will allow any client to simply present a
  1560. <literal>TestingAuthenticationToken</literal> and obtain whatever
  1561. access they request.</para>
  1562. </listitem>
  1563. <listitem>
  1564. <para>Adding a new <literal>AuthenticationProvider</literal> is
  1565. sufficient to support most custom authentication requirements.
  1566. Only unusual requirements would require the
  1567. <literal>ProviderManager</literal> to be replaced with a different
  1568. <literal>AuthenticationManager</literal>.</para>
  1569. </listitem>
  1570. </itemizedlist>
  1571. </sect2>
  1572. </sect1>
  1573. <sect1 id="security-authorization">
  1574. <title>Authorization</title>
  1575. <sect2 id="security-authorization-granted-authorities">
  1576. <title>Granted Authorities</title>
  1577. <para>As briefly mentioned in the Authentication section, all
  1578. <literal>Authentication</literal> implementations are required to
  1579. store an array of <literal>GrantedAuthority</literal> objects. These
  1580. represent the authorities that have been granted to the principal. The
  1581. <literal>GrantedAuthority</literal> objects are inserted into the
  1582. <literal>Authentication</literal> object by the
  1583. <literal>AuthenticationManager</literal> and are later read by
  1584. <literal>AccessDecisionManager</literal>s when making authorization
  1585. decisions.</para>
  1586. <para><literal>GrantedAuthority</literal> is an interface with only
  1587. one method:</para>
  1588. <para><programlisting>public String getAuthority();</programlisting></para>
  1589. <para>This method allows <literal>AccessDecisionManager</literal>s to
  1590. obtain a precise <literal>String</literal> representation of the
  1591. <literal>GrantedAuthority</literal>. By returning a representation as
  1592. a <literal>String</literal>, a <literal>GrantedAuthority</literal> can
  1593. be easily "read" by most <literal>AccessDecisionManager</literal>s. If
  1594. a <literal>GrantedAuthority</literal> cannot be precisely represented
  1595. as a <literal>String</literal>, the
  1596. <literal>GrantedAuthority</literal> is considered "complex" and
  1597. <literal>getAuthority()</literal> must return
  1598. <literal>null</literal>.</para>
  1599. <para>An example of a "complex" <literal>GrantedAuthority</literal>
  1600. would be an implementation that stores a list of operations and
  1601. authority thresholds that apply to different customer account numbers.
  1602. Representing this complex <literal>GrantedAuthority</literal> as a
  1603. <literal>String</literal> would be quite complex, and as a result the
  1604. <literal>getAuthority()</literal> method should return
  1605. <literal>null</literal>. This will indicate to any
  1606. <literal>AccessDecisionManager</literal> that it will need to
  1607. specifically support the <literal>GrantedAuthority</literal>
  1608. implementation in order to understand its contents.</para>
  1609. <para>The Acegi Security System for Spring includes one concrete
  1610. <literal>GrantedAuthority</literal> implementation,
  1611. <literal>GrantedAuthorityImpl</literal>. This allows any
  1612. user-specified <literal>String</literal> to be converted into a
  1613. <literal>GrantedAuthority</literal>. All
  1614. <literal>AuthenticationProvider</literal>s included with the security
  1615. architecture use <literal>GrantedAuthorityImpl</literal> to populate
  1616. the <literal>Authentication</literal> object.</para>
  1617. </sect2>
  1618. <sect2 id="security-authorization-access-decision-managers">
  1619. <title>Access Decision Managers</title>
  1620. <para>The <literal>AccessDecisionManager</literal> is called by the
  1621. <literal>AbstractSecurityInterceptor</literal> and is responsible for
  1622. making final access control decisions. The
  1623. <literal>AccessDecisionManager</literal> interface contains three
  1624. methods:</para>
  1625. <para><programlisting>public void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException;
  1626. public boolean supports(ConfigAttribute attribute);
  1627. public boolean supports(Class clazz);</programlisting></para>
  1628. <para>As can be seen from the first method, the
  1629. <literal>AccessDecisionManager</literal> is passed via method
  1630. parameters all information that is likely to be of value in assessing
  1631. an authorization decision. In particular, passing the secure
  1632. <literal>Object</literal> enables those arguments contained in the
  1633. actual secure object invocation to be inspected. For example, let's
  1634. assume the secure object was a <literal>MethodInvocation</literal>. It
  1635. would be easy to query the <literal>MethodInvocation</literal> for any
  1636. <literal>Customer</literal> argument, and then implement some sort of
  1637. security logic in the <literal>AccessDecisionManager</literal> to
  1638. ensure the principal is permitted to operate on that customer.
  1639. Implementations are expected to throw an
  1640. <literal>AccessDeniedException</literal> if access is denied.</para>
  1641. <para>The <literal>supports(ConfigAttribute)</literal> method is
  1642. called by the <literal>AbstractSecurityInterceptor</literal> at
  1643. startup time to determine if the
  1644. <literal>AccessDecisionManager</literal> can process the passed
  1645. <literal>ConfigAttribute</literal>. The
  1646. <literal>supports(Class)</literal> method is called by a security
  1647. interceptor implementation to ensure the configured
  1648. <literal>AccessDecisionManager</literal> supports the type of secure
  1649. object that the security interceptor will present.</para>
  1650. </sect2>
  1651. <sect2 id="security-authorization-voting-decision-manager">
  1652. <title>Voting Decision Manager</title>
  1653. <para>Whilst users can implement their own
  1654. <literal>AccessDecisionManager</literal> to control all aspects of
  1655. authorization, the Acegi Security System for Spring includes several
  1656. <literal>AccessDecisionManager</literal> implementations that are
  1657. based on voting. Figure 4 illustrates the relevant classes.</para>
  1658. <para><mediaobject>
  1659. <imageobject role="html">
  1660. <imagedata align="center"
  1661. fileref="images/AccessDecisionVoting.gif"
  1662. format="GIF" />
  1663. </imageobject>
  1664. <caption>
  1665. <para>Figure 4: Voting Decision Manager</para>
  1666. </caption>
  1667. </mediaobject></para>
  1668. <para>Using this approach, a series of
  1669. <literal>AccessDecisionVoter</literal> implementations are polled on
  1670. an authorization decision. The
  1671. <literal>AccessDecisionManager</literal> then decides whether or not
  1672. to throw an <literal>AccessDeniedException</literal> based on its
  1673. assessment of the votes.</para>
  1674. <para>The <literal>AccessDecisionVoter</literal> interface has three
  1675. methods:</para>
  1676. <para><programlisting>public int vote(Authentication authentication, Object object, ConfigAttributeDefinition config);
  1677. public boolean supports(ConfigAttribute attribute);
  1678. public boolean supports(Class clazz);</programlisting></para>
  1679. <para>Concrete implementations return an <literal>int</literal>, with
  1680. possible values being reflected in the
  1681. <literal>AccessDecisionVoter</literal> static fields
  1682. <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal>
  1683. and <literal>ACCESS_GRANTED</literal>. A voting implementation will
  1684. return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an
  1685. authorization decision. If it does have an opinion, it must return
  1686. either <literal>ACCESS_DENIED</literal> or
  1687. <literal>ACCESS_GRANTED</literal>.</para>
  1688. <para>There are three concrete
  1689. <literal>AccessDecisionManager</literal>s provided with the Acegi
  1690. Security System for Spring that tally the votes. The
  1691. <literal>ConsensusBased</literal> implementation will grant or deny
  1692. access based on the consensus of non-abstain votes. Properties are
  1693. provided to control behavior in the event of an equality of votes or
  1694. if all votes are abstain. The <literal>AffirmativeBased</literal>
  1695. implementation will grant access if one or more
  1696. <literal>ACCESS_GRANTED</literal> votes were received (ie a deny vote
  1697. will be ignored, provided there was at least one grant vote). Like the
  1698. <literal>ConsensusBased</literal> implementation, there is a parameter
  1699. that controls the behavior if all voters abstain. The
  1700. <literal>UnanimousBased</literal> provider expects unanimous
  1701. <literal>ACCESS_GRANTED</literal> votes in order to grant access,
  1702. ignoring abstains. It will deny access if there is any
  1703. <literal>ACCESS_DENIED</literal> vote. Like the other implementations,
  1704. there is a parameter that controls the behaviour if all voters
  1705. abstain.</para>
  1706. <para>It is possible to implement a custom
  1707. <literal>AccessDecisionManager</literal> that tallies votes
  1708. differently. For example, votes from a particular
  1709. <literal>AccessDecisionVoter</literal> might receive additional
  1710. weighting, whilst a deny vote from a particular voter may have a veto
  1711. effect.</para>
  1712. <para>There are two concrete <literal>AccessDecisionVoter</literal>
  1713. implementations provided with the Acegi Security System for Spring.
  1714. The <literal>RoleVoter</literal> class will vote if any
  1715. ConfigAttribute begins with <literal>ROLE_</literal>. It will vote to
  1716. grant access if there is a <literal>GrantedAuthority</literal> which
  1717. returns a <literal>String</literal> representation (via the
  1718. <literal>getAuthority()</literal> method) exactly equal to one or more
  1719. <literal>ConfigAttributes</literal> starting with
  1720. <literal>ROLE_</literal>. If there is no exact match of any
  1721. <literal>ConfigAttribute</literal> starting with
  1722. <literal>ROLE_</literal>, the <literal>RoleVoter</literal> will vote
  1723. to deny access. If no <literal>ConfigAttribute</literal> begins with
  1724. <literal>ROLE_</literal>, the voter will abstain.
  1725. <literal>RoleVoter</literal> is case sensitive on comparisons as well
  1726. as the <literal>ROLE_</literal> prefix.</para>
  1727. <para>BasicAclEntryVoter is the other concrete voter included with
  1728. Acegi Security. It integrates with Acegi Security's
  1729. <literal>AclManager</literal> (discussed later). This voter is
  1730. designed to have multiple instances in the same application context,
  1731. such as:</para>
  1732. <para><programlisting>&lt;bean id="aclContactReadVoter" class="net.sf.acegisecurity.vote.BasicAclEntryVoter"&gt;
  1733. &lt;property name="processConfigAttribute"&gt;&lt;value&gt;ACL_CONTACT_READ&lt;/value&gt;&lt;/property&gt;
  1734. &lt;property name="processDomainObjectClass"&gt;&lt;value&gt;sample.contact.Contact&lt;/value&gt;&lt;/property&gt;
  1735. &lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
  1736. &lt;property name="requirePermission"&gt;
  1737. &lt;list&gt;
  1738. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
  1739. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.READ"/&gt;
  1740. &lt;/list&gt;
  1741. &lt;/property&gt;
  1742. &lt;/bean&gt;
  1743. &lt;bean id="aclContactDeleteVoter" class="net.sf.acegisecurity.vote.BasicAclEntryVoter"&gt;
  1744. &lt;property name="processConfigAttribute"&gt;&lt;value&gt;ACL_CONTACT_DELETE&lt;/value&gt;&lt;/property&gt;
  1745. &lt;property name="processDomainObjectClass"&gt;&lt;value&gt;sample.contact.Contact&lt;/value&gt;&lt;/property&gt;
  1746. &lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
  1747. &lt;property name="requirePermission"&gt;
  1748. &lt;list&gt;
  1749. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
  1750. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.DELETE"/&gt;
  1751. &lt;/list&gt;
  1752. &lt;/property&gt;
  1753. &lt;/bean&gt;</programlisting></para>
  1754. <para>In the above example, you'd define
  1755. <literal>ACL_CONTACT_READ</literal> or
  1756. <literal>ACL_CONTACT_DELETE</literal> against some methods on a
  1757. <literal>MethodSecurityInterceptor</literal> or
  1758. <literal>AspectJSecurityInterceptor</literal>. When those methods are
  1759. invoked, the above applicable voter defined above would vote to grant
  1760. or deny access. The voter would look at the method invocation to
  1761. locate the first argument of type
  1762. <literal>sample.contact.Contact</literal>, and then pass that
  1763. <literal>Contact</literal> to the <literal>AclManager</literal>. The
  1764. <literal>AclManager</literal> will then return an access control list
  1765. (ACL) that applies to the current <literal>Authentication</literal>.
  1766. Assuming that ACL contains one of the listed
  1767. <literal>requirePermission</literal>s, the voter will vote to grant
  1768. access. If the ACL does not contain one of the permissions defined
  1769. against the voter, the voter will vote to deny access.
  1770. <literal>BasicAclEntryVoter</literal> is an important class as it
  1771. allows you to build truly complex applications with domain object
  1772. security entirely defined in the application context. If you're
  1773. interested in learning more about Acegi Security's ACL capabilities
  1774. and how best to apply them, please see the ACL and "After Invocation"
  1775. sections of this reference guide, and the Contacts sample
  1776. application.</para>
  1777. <para>It is also possible to implement a custom
  1778. <literal>AccessDecisionVoter</literal>. Several examples are provided
  1779. in the Acegi Security System for Spring unit tests, including
  1780. <literal>ContactSecurityVoter</literal> and
  1781. <literal>DenyVoter</literal>. The
  1782. <literal>ContactSecurityVoter</literal> abstains from voting decisions
  1783. where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
  1784. <literal>ConfigAttribute</literal> is not found. If voting, it queries
  1785. the <literal>MethodInvocation</literal> to extract the owner of the
  1786. <literal>Contact</literal> object that is subject of the method call.
  1787. It votes to grant access if the <literal>Contact</literal> owner
  1788. matches the principal presented in the
  1789. <literal>Authentication</literal> object. It could have just as easily
  1790. compared the <literal>Contact</literal> owner with some
  1791. <literal>GrantedAuthority</literal> the
  1792. <literal>Authentication</literal> object presented. All of this is
  1793. achieved with relatively few lines of code and demonstrates the
  1794. flexibility of the authorization model.</para>
  1795. </sect2>
  1796. <sect2 id="security-authorization-taglib">
  1797. <title>Authorization-Related Tag Libraries</title>
  1798. <para>The Acegi Security System for Spring comes bundled with several
  1799. JSP tag libraries that eases JSP writing. The tag libraries are known
  1800. as <literal>authz</literal> and provide a range of different
  1801. services.</para>
  1802. <para>All taglib classes are included in the core
  1803. <literal>acegi-security-xx.jar</literal> file, with the
  1804. <literal>authz.tld</literal> located in the JAR's
  1805. <literal>META-INF</literal> directory. This means for JSP 1.2+ web
  1806. containers you can simply include the JAR in the WAR's
  1807. <literal>WEB-INF/lib</literal> directory and it will be available. If
  1808. you're using a JSP 1.1 container, you'll need to declare the JSP
  1809. taglib in your <literal>web.xml file</literal>, and include
  1810. <literal>authz.tld</literal> in the <literal>WEB-INF/lib</literal>
  1811. directory. The following fragment is added to
  1812. <literal>web.xml</literal>:</para>
  1813. <para><programlisting>&lt;taglib&gt;
  1814. &lt;taglib-uri&gt;http://acegisecurity.sf.net/authz&lt;/taglib-uri&gt;
  1815. &lt;taglib-location&gt;/WEB-INF/authz.tld&lt;/taglib-location&gt;
  1816. &lt;/taglib&gt;</programlisting></para>
  1817. <sect3>
  1818. <title>AuthorizeTag</title>
  1819. <para><literal>AuthorizeTag</literal> is used to include content if
  1820. the current principal holds certain
  1821. <literal>GrantedAuthority</literal>s.</para>
  1822. <para>The following JSP fragment illustrates how to use the
  1823. <literal>AuthorizeTag</literal>:</para>
  1824. <para><programlisting>&lt;authz:authorize ifAllGranted="ROLE_SUPERVISOR"&gt;
  1825. &lt;td&gt;
  1826. &lt;A HREF="del.htm?id=&lt;c:out value="${contact.id}"/&gt;"&gt;Del&lt;/A&gt;
  1827. &lt;/td&gt;
  1828. &lt;/authz:authorize&gt;</programlisting></para>
  1829. <para>This tag would cause the tag's body to be output if the
  1830. principal has been granted ROLE_SUPERVISOR.</para>
  1831. <para>The <literal>authz:authorize</literal> tag declares the
  1832. following attributes:</para>
  1833. <para><itemizedlist spacing="compact">
  1834. <listitem>
  1835. <para><literal>ifAllGranted</literal>: All the listed roles
  1836. must be granted for the tag to output its body.</para>
  1837. </listitem>
  1838. <listitem>
  1839. <para><literal>ifAnyGranted</literal>: Any of the listed roles
  1840. must be granted for the tag to output its body.</para>
  1841. </listitem>
  1842. <listitem>
  1843. <para><literal>ifNotGranted</literal>: None of the listed
  1844. roles must be granted for the tag to output its body.</para>
  1845. </listitem>
  1846. </itemizedlist></para>
  1847. <para>You'll note that in each attribute you can list multiple
  1848. roles. Simply separate the roles using a comma. The
  1849. <literal>authorize</literal> tag ignores whitespace in
  1850. attributes.</para>
  1851. <para>The tag library logically ANDs all of it's parameters
  1852. together. This means that if you combine two or more attributes, all
  1853. attributes must be true for the tag to output it's body. Don't add
  1854. an <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an
  1855. <literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be
  1856. surprised to never see the tag's body.</para>
  1857. <para>By requiring all attributes to return true, the authorize tag
  1858. allows you to create more complex authorization scenarios. For
  1859. example, you could declare an
  1860. <literal>ifAllGranted="ROLE_SUPERVISOR"</literal> and an
  1861. <literal>ifNotGranted="ROLE_NEWBIE_SUPERVISOR"</literal> in the same
  1862. tag, in order to prevent new supervisors from seeing the tag body.
  1863. However it would no doubt be simpler to use
  1864. <literal>ifAllGranted="ROLE_EXPERIENCED_SUPERVISOR"</literal> rather
  1865. than inserting NOT conditions into your design.</para>
  1866. <para>One last item: the tag verifies the authorizations in a
  1867. specific order: first <literal>ifNotGranted</literal>, then
  1868. <literal>ifAllGranted</literal>, and finally,
  1869. <literal>ifAnyGranted</literal>.</para>
  1870. </sect3>
  1871. <sect3>
  1872. <title>AuthenticationTag</title>
  1873. <para><literal>AuthenticationTag</literal> is used to simply output
  1874. the current principal to the web page.</para>
  1875. <para>The following JSP fragment illustrates how to use the
  1876. <literal>AuthenticationTag</literal>:</para>
  1877. <para><programlisting>&lt;authz:authentication operation="principal"/&gt;</programlisting></para>
  1878. <para>This tag would cause the principal's name to be output. The
  1879. taglib properly supports the various types of principals that can
  1880. exist in the <literal>Authentication</literal> object, such as a
  1881. <literal>String</literal> or <literal>UserDetails</literal>
  1882. instance.</para>
  1883. <para>The "operation" attribute must always be "principal". This may
  1884. be expanded in the future, such as obtaining other
  1885. <literal>Authentication</literal>-related properties such as email
  1886. address or telephone numbers.</para>
  1887. </sect3>
  1888. <sect3>
  1889. <title>AclTag</title>
  1890. <para><literal>AclTag</literal> is used to include content if the
  1891. current principal has a ACL to the indicated domain object.</para>
  1892. <para>The following JSP fragment illustrates how to use the
  1893. <literal>AclTag</literal>:</para>
  1894. <para><programlisting>&lt;authz:acl domainObject="${contact}" hasPermission="16,1"&gt;
  1895. &lt;td&gt;&lt;A HREF="&lt;c:url value="del.htm"&gt;&lt;c:param name="contactId" value="${contact.id}"/&gt;&lt;/c:url&gt;"&gt;Del&lt;/A&gt;&lt;/td&gt;
  1896. &lt;/authz:acl&gt;</programlisting></para>
  1897. <para>This tag would cause the tag's body to be output if the
  1898. principal holds either permission 16 or permission 1 for the
  1899. "contact" domain object. The numbers are actually integers that are
  1900. used with <literal>AbstractBasicAclEntry</literal> bit masking.
  1901. Please refer tro the ACL section of this reference guide to
  1902. understand more about the ACL capabilities of Acegi Security.</para>
  1903. </sect3>
  1904. </sect2>
  1905. <sect2 id="security-authorization-recommendations">
  1906. <title>Authorization Recommendations</title>
  1907. <para>Given there are several ways to achieve similar authorization
  1908. outcomes in the Acegi Security System for Spring, the following
  1909. general recommendations are made:</para>
  1910. <itemizedlist>
  1911. <listitem>
  1912. <para>Grant authorities using
  1913. <literal>GrantedAuthorityImpl</literal> where possible. Because it
  1914. is already supported by the Acegi Security System for Spring, you
  1915. avoid the need to create custom
  1916. <literal>AuthenticationManager</literal> or
  1917. <literal>AuthenticationProvider</literal> implementations simply
  1918. to populate the <literal>Authentication</literal> object with a
  1919. custom <literal>GrantedAuthority</literal>.</para>
  1920. </listitem>
  1921. <listitem>
  1922. <para>Writing an <literal>AccessDecisionVoter</literal>
  1923. implementation and using either <literal>ConsensusBased</literal>,
  1924. <literal>AffirmativeBased</literal> or
  1925. <literal>UnanimousBased</literal> as the
  1926. <literal>AccessDecisionManager</literal> may be the best approach
  1927. to implementing your custom access decision rules.</para>
  1928. </listitem>
  1929. </itemizedlist>
  1930. </sect2>
  1931. </sect1>
  1932. <sect1 id="afterinvocation">
  1933. <title>After Invocation Handling</title>
  1934. <sect2 id="afterinvocation-overview">
  1935. <title>Overview</title>
  1936. <para>Whilst the <literal>AccessDecisionManager</literal> is called by
  1937. the <literal>AbstractSecurityInterceptor</literal> before proceeding
  1938. with the secure object invocation, some applications need a way of
  1939. modifying the object actually returned by the secure object
  1940. invocation. Whilst you could easily implement your own AOP concern to
  1941. achieve this, Acegi Security provides a convenient hook that has
  1942. several concrete implementations that integrate with its ACL
  1943. capabilities.</para>
  1944. <para>Figure 5 illustrates Acegi Security's
  1945. <literal>AfterInvocationManager</literal> and its concrete
  1946. implementations.</para>
  1947. <para><mediaobject>
  1948. <imageobject role="html">
  1949. <imagedata align="center" fileref="images/AfterInvocation.gif"
  1950. format="GIF" />
  1951. </imageobject>
  1952. <caption>
  1953. <para>Figure 5: After Invocation Implementation</para>
  1954. </caption>
  1955. </mediaobject></para>
  1956. <para>Like many other parts of Acegi Security,
  1957. <literal>AfterInvocationManager</literal> has a single concrete
  1958. implementation, <literal>AfterInvocationProvider</literal>, which
  1959. polls a list of <literal>AfterInvocationProvider</literal>s. Each
  1960. <literal>AfterInvocationProvider</literal> is allowed to modify the
  1961. return object or throw an <literal>AccessDeniedException</literal>.
  1962. Indeed multiple providers can modify the object, as the result of the
  1963. previous provider is passed to the next in the list. Let's now
  1964. consider our ACL-aware implementations of
  1965. <literal>AfterInvocationProvider</literal>.</para>
  1966. <para>Please be aware that if you're using
  1967. <literal>AfterInvocationManager</literal>, you will still need
  1968. configuration attributes that allow the
  1969. <literal>MethodSecurityInterceptor</literal>'s
  1970. <literal>AccessDecisionManager</literal> to allow an operation. If
  1971. you're using the typical Acegi Security included
  1972. <literal>AccessDecisionManager</literal> implementations, having no
  1973. configuration attributes defined for a particular secure method
  1974. invocation will cause each <literal>AccessDecisionVoter</literal> to
  1975. abstain from voting. In turn, if the
  1976. <literal>AccessDecisionManager</literal> property
  1977. "<literal>allowIfAllAbstainDecisions</literal>" is
  1978. <literal>false</literal>, an <literal>AccessDeniedException</literal>
  1979. will be thrown. You may avoid this potential issue by either (i)
  1980. setting "<literal>allowIfAllAbstainDecisions</literal>" to
  1981. <literal>true</literal> (although this is generally not recommended)
  1982. or (ii) simply ensure that there is at least one configuration
  1983. attribute that an <literal>AccessDecisionVoter</literal> will vote to
  1984. grant access for. This latter (recommended) approach is usually
  1985. achieved through a <literal>ROLE_USER</literal> or
  1986. <literal>ROLE_AUTHENTICATED</literal> configuration attribute.</para>
  1987. </sect2>
  1988. <sect2 id="afterinvocation-acl-aware">
  1989. <title>ACL-Aware AfterInvocationProviders</title>
  1990. <para>A common services layer method we've all written at one stage or
  1991. another looks like this:</para>
  1992. <para><programlisting>public Contact getById(Integer id);</programlisting></para>
  1993. <para>Quite often, only principals with permission to read the
  1994. <literal>Contact</literal> should be allowed to obtain it. In this
  1995. situation the <literal>AccessDecisionManager</literal> approach
  1996. provided by the <literal>AbstractSecurityInterceptor</literal> will
  1997. not suffice. This is because the identity of the
  1998. <literal>Contact</literal> is all that is available before the secure
  1999. object is invoked. The
  2000. <literal>BasicAclAfterInvocationProvider</literal> delivers a
  2001. solution, and is configured as follows:</para>
  2002. <para><programlisting>&lt;bean id="afterAclRead" class="net.sf.acegisecurity.afterinvocation.BasicAclEntryAfterInvocationProvider"&gt;
  2003. &lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
  2004. &lt;property name="requirePermission"&gt;
  2005. &lt;list&gt;
  2006. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
  2007. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.READ"/&gt;
  2008. &lt;/list&gt;
  2009. &lt;/property&gt;
  2010. &lt;/bean&gt;</programlisting></para>
  2011. <para>In the above example, the <literal>Contact</literal> will be
  2012. retrieved and passed to the
  2013. <literal>BasicAclEntryAfterInvocationProvider</literal>. The provider
  2014. will thrown an <literal>AccessDeniedException</literal> if one of the
  2015. listed <literal>requirePermission</literal>s is not held by the
  2016. <literal>Authentication</literal>. The
  2017. <literal>BasicAclEntryAfterInvocationProvider</literal> queries the
  2018. <literal>AclManager</literal> to determine the ACL that applies for
  2019. this domain object to this <literal>Authentication</literal>.</para>
  2020. <para>Similar to the
  2021. <literal>BasicAclEntryAfterInvocationProvider</literal> is
  2022. <literal>BasicAclEntryAfterInvocationCollectionFilteringProvider</literal>.
  2023. It is designed to remove <literal>Collection</literal> or array
  2024. elements for which a principal does not have access. It never thrown
  2025. an <literal>AccessDeniedException</literal> - simply silently removes
  2026. the offending elements. The provider is configured as follows:</para>
  2027. <para><programlisting>&lt;bean id="afterAclCollectionRead" class="net.sf.acegisecurity.afterinvocation.BasicAclEntryAfterInvocationCollectionFilteringProvider"&gt;
  2028. &lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
  2029. &lt;property name="requirePermission"&gt;
  2030. &lt;list&gt;
  2031. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
  2032. &lt;ref local="net.sf.acegisecurity.acl.basic.SimpleAclEntry.READ"/&gt;
  2033. &lt;/list&gt;
  2034. &lt;/property&gt;
  2035. &lt;/bean&gt;</programlisting></para>
  2036. <para>As you can imagine, the returned <literal>Object</literal> must
  2037. be a <literal>Collection</literal> or array for this provider to
  2038. operate. It will remove any element if the
  2039. <literal>AclManager</literal> indicates the
  2040. <literal>Authentication</literal> does not hold one of the listed
  2041. <literal>requirePermission</literal>s.</para>
  2042. <para>The Contacts sample application demonstrates these two
  2043. <literal>AfterInvocationProvider</literal>s.</para>
  2044. </sect2>
  2045. </sect1>
  2046. <sect1 id="security-run-as">
  2047. <title>Run-As Authentication Replacement</title>
  2048. <sect2 id="security-run-as-purpose">
  2049. <title>Purpose</title>
  2050. <para>The <literal>AbstractSecurityInterceptor</literal> is able to
  2051. temporarily replace the <literal>Authentication</literal> object in
  2052. the <literal>SecureContext</literal> and
  2053. <literal>ContextHolder</literal> during the
  2054. <literal>SecurityInterceptorCallback</literal>. This only occurs if
  2055. the original <literal>Authentication</literal> object was successfully
  2056. processed by the <literal>AuthenticationManager</literal> and
  2057. <literal>AccessDecisionManager</literal>. The
  2058. <literal>RunAsManager</literal> will indicate the replacement
  2059. <literal>Authentication</literal> object, if any, that should be used
  2060. during the <literal>SecurityInterceptorCallback</literal>.</para>
  2061. <para>By temporarily replacing the <literal>Authentication</literal>
  2062. object during a <literal>SecurityInterceptorCallback</literal>, the
  2063. secured invocation will be able to call other objects which require
  2064. different authentication and authorization credentials. It will also
  2065. be able to perform any internal security checks for specific
  2066. <literal>GrantedAuthority</literal> objects. Because Acegi Security
  2067. provides a number of helper classes that automatically configure
  2068. remoting protocols based on the contents of the
  2069. <literal>ContextHolder</literal>, these run-as replacements are
  2070. particularly useful when calling remote web services.</para>
  2071. </sect2>
  2072. <sect2 id="security-run-as-usage">
  2073. <title>Usage</title>
  2074. <para>A <literal>RunAsManager</literal> interface is provided by the
  2075. Acegi Security System for Spring:</para>
  2076. <para><programlisting>public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config);
  2077. public boolean supports(ConfigAttribute attribute);
  2078. public boolean supports(Class clazz);</programlisting></para>
  2079. <para>The first method returns the <literal>Authentication</literal>
  2080. object that should replace the existing
  2081. <literal>Authentication</literal> object for the duration of the
  2082. method invocation. If the method returns <literal>null</literal>, it
  2083. indicates no replacement should be made. The second method is used by
  2084. the <literal>AbstractSecurityInterceptor</literal> as part of its
  2085. startup validation of configuration attributes. The
  2086. <literal>supports(Class)</literal> method is called by a security
  2087. interceptor implementation to ensure the configured
  2088. <literal>RunAsManager</literal> supports the type of secure object
  2089. that the security interceptor will present.</para>
  2090. <para>One concrete implementation of a <literal>RunAsManager</literal>
  2091. is provided with the Acegi Security System for Spring. The
  2092. <literal>RunAsManagerImpl</literal> class returns a replacement
  2093. <literal>RunAsUserToken</literal> if any
  2094. <literal>ConfigAttribute</literal> starts with
  2095. <literal>RUN_AS_</literal>. If any such
  2096. <literal>ConfigAttribute</literal> is found, the replacement
  2097. <literal>RunAsUserToken</literal> will contain the same principal,
  2098. credentials and granted authorities as the original
  2099. <literal>Authentication</literal> object, along with a new
  2100. <literal>GrantedAuthorityImpl</literal> for each
  2101. <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
  2102. new <literal>GrantedAuthorityImpl</literal> will be prefixed with
  2103. <literal>ROLE_</literal>, followed by the <literal>RUN_AS</literal>
  2104. <literal>ConfigAttribute</literal>. For example, a
  2105. <literal>RUN_AS_SERVER</literal> will result in the replacement
  2106. <literal>RunAsUserToken</literal> containing a
  2107. <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
  2108. <para>The replacement <literal>RunAsUserToken</literal> is just like
  2109. any other <literal>Authentication</literal> object. It needs to be
  2110. authenticated by the <literal>AuthenticationManager</literal>,
  2111. probably via delegation to a suitable
  2112. <literal>AuthenticationProvider</literal>. The
  2113. <literal>RunAsImplAuthenticationProvider</literal> performs such
  2114. authentication. It simply accepts as valid any
  2115. <literal>RunAsUserToken</literal> presented.</para>
  2116. <para>To ensure malicious code does not create a
  2117. <literal>RunAsUserToken</literal> and present it for guaranteed
  2118. acceptance by the <literal>RunAsImplAuthenticationProvider</literal>,
  2119. the hash of a key is stored in all generated tokens. The
  2120. <literal>RunAsManagerImpl</literal> and
  2121. <literal>RunAsImplAuthenticationProvider</literal> is created in the
  2122. bean context with the same key:</para>
  2123. <para><programlisting>&lt;bean id="runAsManager" class="net.sf.acegisecurity.runas.RunAsManagerImpl"&gt;
  2124. &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
  2125. &lt;/bean&gt;</programlisting><programlisting>&lt;bean id="runAsAuthenticationProvider" class="net.sf.acegisecurity.runas.RunAsImplAuthenticationProvider"&gt;
  2126. &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
  2127. &lt;/bean&gt;</programlisting></para>
  2128. <para>By using the same key, each <literal>RunAsUserToken</literal>
  2129. can be validated it was created by an approved
  2130. <literal>RunAsManagerImpl</literal>. The
  2131. <literal>RunAsUserToken</literal> is immutable after creation for
  2132. security reasons.</para>
  2133. </sect2>
  2134. </sect1>
  2135. <sect1 id="security-ui">
  2136. <title>User Interfacing with the ContextHolder</title>
  2137. <sect2 id="security-ui-purpose">
  2138. <title>Purpose</title>
  2139. <para>Everything presented so far assumes one thing: the
  2140. <literal>ContextHolder</literal> is populated with a valid
  2141. <literal>SecureContext</literal>, which in turn contains a valid
  2142. <literal>Authentication</literal> object. Developers are free to do
  2143. this in whichever way they like, such as directly calling the relevant
  2144. objects at runtime. However, several classes have been provided to
  2145. make this process transparent in many situations. We call these
  2146. classes "authentication mechanisms".</para>
  2147. <para>The <literal>net.sf.acegisecurity.ui</literal> package provides
  2148. what we call "authentication processing mechanisms". An authentication
  2149. processing mechanism is solely concerned with received an
  2150. authentication request from the principal, testing if it seems valid,
  2151. and if so, placing the authentication request token onto the
  2152. ContextHolder. Of course, if the authentication request is invalid,
  2153. the authentication processing mechanism is responsible for informing
  2154. the principal in whatever way is appropriate to the protocol.</para>
  2155. <para>Recall the HttpSessionContextIntegrationFilter (discussed in the
  2156. context section) is responsible for storing the ContextHolder contents
  2157. between invocations. This means no authentication processing mechanism
  2158. need ever interact directly with HttpSession. Indeed
  2159. HttpSessionContextIntegrationFilter has been designed to minimise the
  2160. unnecessary creation of HttpSessions, as might occur when using Basic
  2161. authentication for example.</para>
  2162. <para>There are several authentication processing mechanisms included
  2163. with Acegi Security, which will be briefly discussed in this chapter.
  2164. The most popular (and almost always recommended) approach is HTTP Form
  2165. Authentication, which uses a login form to authenticate the user.
  2166. Another approach (commonly use with web services) is HTTP Basic
  2167. Authentication, which allows clients to use HTTP headers to present
  2168. authentication information to the Acegi Security System for Spring.
  2169. Alternatively, you can also use Yale Central Authentication Service
  2170. (CAS) for enterprise-wide single sign on. The final (and generally
  2171. unrecommended) approach is via Container Adapters, which allow
  2172. supported web containers to perform the authentication themselves.
  2173. HTTP Form Authentication and Basic Authentication is discussed below,
  2174. whilst CAS and Container Adapters are discussed in separate sections
  2175. of this document.</para>
  2176. </sect2>
  2177. <sect2 id="security-ui-http-form">
  2178. <title>HTTP Form Authentication</title>
  2179. <para>HTTP Form Authentication involves using the
  2180. <literal>AuthenticationProcessingFilter</literal> to process a login
  2181. form. The login form simply contains <literal>j_username</literal> and
  2182. <literal>j_password</literal> input fields, and posts to a URL that is
  2183. monitored by the filter (by default
  2184. <literal>j_acegi_security_check</literal>). The filter is defined in
  2185. <literal>web.xml</literal> behind a
  2186. <literal>FilterToBeanProxy</literal> as follows:</para>
  2187. <para><programlisting>&lt;filter&gt;
  2188. &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
  2189. &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
  2190. &lt;init-param&gt;
  2191. &lt;param-name&gt;targetClass&lt;/param-name&gt;
  2192. &lt;param-value&gt;net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter&lt;/param-value&gt;
  2193. &lt;/init-param&gt;
  2194. &lt;/filter&gt;
  2195. &lt;filter-mapping&gt;
  2196. &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
  2197. &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  2198. &lt;/filter-mapping&gt;</programlisting></para>
  2199. <para>For a discussion of <literal>FilterToBeanProxy</literal>, please
  2200. refer to the Filters section. The application context will need to
  2201. define the <literal>AuthenticationProcessingFilter</literal>:</para>
  2202. <para><programlisting>&lt;bean id="authenticationProcessingFilter" class="net.sf.acegisecurity.ui.webapp.AuthenticationProcessingFilter"&gt;
  2203. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  2204. &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/acegilogin.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
  2205. &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
  2206. &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_acegi_security_check&lt;/value&gt;&lt;/property&gt;
  2207. &lt;/bean&gt;</programlisting></para>
  2208. <para>The configured <literal>AuthenticationManager</literal>
  2209. processes each authentication request. If authentication fails, the
  2210. browser will be redirected to the
  2211. <literal>authenticationFailureUrl</literal>. The
  2212. <literal>AuthenticationException</literal> will be placed into the
  2213. <literal>HttpSession</literal> attribute indicated by
  2214. <literal>AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY</literal>,
  2215. enabling a reason to be provided to the user on the error page.</para>
  2216. <para>If authentication is successful, the resulting
  2217. <literal>Authentication</literal> object will be placed into the
  2218. <literal>ContextHolder</literal>.</para>
  2219. <para>Once the <literal>ContextHolder</literal> has been updated, the
  2220. browser will need to be redirected to the target URL. The target URL
  2221. is usually indicated by the <literal>HttpSession</literal> attribute
  2222. specified by
  2223. <literal>AbstractProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY</literal>.
  2224. This attribute is automatically set by the
  2225. <literal>SecurityEnforcementFilter</literal> when an
  2226. <literal>AuthenticationException</literal> occurs, so that after login
  2227. is completed the user can return to what they were trying to access.
  2228. If for some reason the <literal>HttpSession</literal> does not
  2229. indicate the target URL, the browser will be redirected to the
  2230. <literal>defaultTargetUrl</literal> property.</para>
  2231. <para>Because this authentication approach is fully contained within a
  2232. single web application, HTTP Form Authentication is recommended to be
  2233. used instead of Container Adapters.</para>
  2234. </sect2>
  2235. <sect2 id="security-ui-http-basic">
  2236. <title>HTTP Basic Authentication</title>
  2237. <para>The Acegi Security System for Spring provides a
  2238. <literal>BasicProcessingFilter</literal> which is capable of
  2239. processing basic authentication credentials presented in HTTP headers.
  2240. This can be used for authenticating calls made by Spring remoting
  2241. protocols (such as Hessian and Burlap), as well as normal user agents
  2242. (such as Internet Explorer and Navigator). The standard governing HTTP
  2243. Basic Authentication is defined by RFC 1945, Section 11, and the
  2244. <literal>BasicProcessingFilter</literal> conforms with this RFC. Basic
  2245. Authentication is an attractive approach to authentication, because it
  2246. is very widely deployed in user agents and implementation is extremely
  2247. simple (it's just a Base64 encoding of the username:password,
  2248. specified in a HTTP header).</para>
  2249. <para>To implement HTTP Basic Authentication, it is necessary to
  2250. define <literal>BasicProcessingFilter</literal> in the fitler chain.
  2251. The application context will need to define the
  2252. <literal>BasicProcessingFilter</literal> and its required
  2253. collaborator:</para>
  2254. <para><programlisting>&lt;bean id="basicProcessingFilter" class="net.sf.acegisecurity.ui.basicauth.BasicProcessingFilter"&gt;
  2255. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  2256. &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;
  2257. &lt;/bean&gt;
  2258. &lt;bean id="authenticationEntryPoint" class="net.sf.acegisecurity.ui.basicauth.BasicProcessingFilterEntryPoint"&gt;
  2259. &lt;property name="realmName"&gt;&lt;value&gt;Name Of Your Realm&lt;/value&gt;&lt;/property&gt;
  2260. &lt;/bean&gt;</programlisting></para>
  2261. <para>The configured <literal>AuthenticationManager</literal>
  2262. processes each authentication request. If authentication fails, the
  2263. configured <literal>AuthenticationEntryPoint</literal> will be used to
  2264. retry the authentication process. Usually you will use the
  2265. <literal>BasicProcessingFilterEntryPoint</literal>, which returns a
  2266. 401 response with a suitable header to retry HTTP Basic
  2267. authentication. If authentication is successful, the resulting
  2268. <literal>Authentication</literal> object will be placed into the
  2269. <literal>ContextHolder</literal>.</para>
  2270. <para>If the authentication event was successful, or authentication
  2271. was not attempted because the HTTP header did not contain a supported
  2272. authentication request, the filter chain will continue as normal. The
  2273. only time the filter chain will be interrupted is if authentication
  2274. fails and the <literal>AuthenticationEntryPoint</literal> is called,
  2275. as discussed in the previous paragraph.</para>
  2276. </sect2>
  2277. <sect2 id="security-ui-http-digest">
  2278. <title>HTTP Digest Authentication</title>
  2279. <para>The Acegi Security System for Spring provides a
  2280. <literal>DigestProcessingFilter</literal> which is capable of
  2281. processing digest authentication credentials presented in HTTP
  2282. headers. Digest Authentication attempts to solve many of the
  2283. weakenesses of Basic authentication, specifically by ensuring
  2284. credentials are never sent in clear text across the wire. Many user
  2285. agents support Digest Authentication, including FireFox and Internet
  2286. Explorer. The standard governing HTTP Digest Authentication is defined
  2287. by RFC 2617, which updates an earlier version of the Digest
  2288. Authentication standard prescribed by RFC 2069. Most user agents
  2289. implement RFC 2617. The Acegi Security
  2290. <literal>DigestProcessingFilter</literal> is compatible with the
  2291. "<literal>auth</literal>" quality of protection
  2292. (<literal>qop</literal>) prescribed by RFC 2617, which also provides
  2293. backward compatibility with RFC 2069. Digest Authentication is a
  2294. highly attractive option if you need to use unencrypted HTTP (ie no
  2295. TLS/HTTPS) and wish to maximise security of the authentication
  2296. process. Indeed Digest Authentication is a mandatory requirement for
  2297. the WebDAV protocol, as noted by RFC 2518 Section 17.1, so we should
  2298. expect to see it increasingly deployed and replacing Basic
  2299. Authentication.</para>
  2300. <para>Digest Authentication is definitely the most secure choice
  2301. between Form Authentication, Basic Authentication and Digest
  2302. Authentication, although extra security also means more complex user
  2303. agent implementations. Central to Digest Authentication is a "nonce".
  2304. This is a value the server generates. Acegi Security's nonce adopts
  2305. the following format:</para>
  2306. <para><programlisting>base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key))
  2307. expirationTime: The date and time when the nonce expires, expressed in milliseconds
  2308. key: A private key to prevent modification of the nonce token
  2309. </programlisting></para>
  2310. <para>The <literal>DigestProcessingFilterEntryPoint</literal> has a
  2311. property specifying the <literal>key</literal> used for generating the
  2312. nonce tokens, along with a <literal>nonceValiditySeconds</literal>
  2313. property for determining the expiration time (default 300, which
  2314. equals five minutes). Whilstever the nonce is valid, the digest is
  2315. computed by concatenating various strings including the username,
  2316. password, nonce, URI being requested, a client-generated nonce (merely
  2317. a random value which the user agent generates each request), the realm
  2318. name etc, then performing an MD5 hash. Both the server and user agent
  2319. perform this digest computation, resulting in different hash codes if
  2320. they disagree on an included value (eg password). In the Acegi
  2321. Security implementation, if the server-generated nonce has merely
  2322. expired (but the digest was otherwise valid), the
  2323. <literal>DigestProcessingFilterEntryPoint</literal> will send a
  2324. <literal>"stale=true"</literal> header. This tells the user agent
  2325. there is no need to disturb the user (as the password and username etc
  2326. is correct), but simply to try again using a new nonce.</para>
  2327. <para>An appropriate value for
  2328. <literal>DigestProcessingFilterEntryPoint</literal>'s
  2329. <literal>nonceValiditySeconds</literal> parameter will depend on your
  2330. application. Extremely secure applications should note that an
  2331. intercepted authentication header can be used to impersonate the
  2332. principal until the <literal>expirationTime</literal> contained in the
  2333. nonce is reached. This is the key principle when selecting an
  2334. appropriate setting, but it would be unusual for immensly secure
  2335. applications to not be running over TLS/HTTPS in the first
  2336. instance.</para>
  2337. <para>Because of the more complex implementation of Digest
  2338. Authentication, there are often user agent issues. For example,
  2339. Internet Explorer fails to present an "<literal>opaque</literal>"
  2340. token on subsequent requests in the same session. The Acegi Security
  2341. filters therefore encapsulate all state information into the
  2342. "<literal>nonce</literal>" token instead. In our testing, the Acegi
  2343. Security implementation works reliably with FireFox and Internet
  2344. Explorer, correctly handling nonce timeouts etc.</para>
  2345. <para>Now that we've reviewed the theory, let's see how to use it. To
  2346. implement HTTP Digest Authentication, it is necessary to define
  2347. <literal>DigestProcessingFilter</literal> in the fitler chain. The
  2348. application context will need to define the
  2349. <literal>DigestProcessingFilter</literal> and its required
  2350. collaborators:</para>
  2351. <para><programlisting>&lt;bean id="digestProcessingFilter" class="net.sf.acegisecurity.ui.digestauth.DigestProcessingFilter"&gt;
  2352. &lt;property name="authenticationDao"&gt;&lt;ref local="jdbcDaoImpl"/&gt;&lt;/property&gt;
  2353. &lt;property name="authenticationEntryPoint"&gt;&lt;ref local="digestProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
  2354. &lt;property name="userCache"&gt;&lt;ref local="userCache"/&gt;&lt;/property&gt;
  2355. &lt;/bean&gt;
  2356. &lt;bean id="digestProcessingFilterEntryPoint" class="net.sf.acegisecurity.ui.digestauth.DigestProcessingFilterEntryPoint"&gt;
  2357. &lt;property name="realmName"&gt;&lt;value&gt;Contacts Realm via Digest Authentication&lt;/value&gt;&lt;/property&gt;
  2358. &lt;property name="key"&gt;&lt;value&gt;acegi&lt;/value&gt;&lt;/property&gt;
  2359. &lt;property name="nonceValiditySeconds"&gt;&lt;value&gt;10&lt;/value&gt;&lt;/property&gt;
  2360. &lt;/bean&gt;</programlisting></para>
  2361. <para>The configured <literal>AuthenticationDao</literal> is needed
  2362. because <literal>DigestProcessingFilter</literal> must have direct
  2363. access to the clear text password of a user. Digest Authentication
  2364. will NOT work if you are using encoded passwords in your DAO. The DAO
  2365. collaborator, along with the <literal>UserCache</literal>, are
  2366. typically shared directly with a
  2367. <literal>DaoAuthenticationProvider</literal>. The
  2368. <literal>authenticationEntryPoint</literal> property must be
  2369. <literal>DigestProcessingFilterEntryPoint</literal>, so that
  2370. <literal>DigestProcessingFilter</literal> can obtain the correct
  2371. <literal>realmName</literal> and <literal>key</literal> for digest
  2372. calculations.</para>
  2373. <para>Like <literal>BasicAuthenticationFilter</literal>, if
  2374. authentication is successful an <literal>Authentication</literal>
  2375. request token will be placed into the
  2376. <literal>ContextHolder</literal>. If the authentication event was
  2377. successful, or authentication was not attempted because the HTTP
  2378. header did not contain a Digest Authentication request, the filter
  2379. chain will continue as normal. The only time the filter chain will be
  2380. interrupted is if authentication fails and the
  2381. <literal>AuthenticationEntryPoint</literal> is called, as discussed in
  2382. the previous paragraph.</para>
  2383. <para>Digest Authentication's RFC offers a range of additional
  2384. features to further increase security. For example, the nonce can be
  2385. changed on every request. Despite this, the Acegi Security
  2386. implementation was designed to minimise the complexity of the
  2387. implementation (and the doubtless user agent incompatibilities that
  2388. would emerge), and avoid needing to store server-side state. You are
  2389. invited to review RFC 2617 if you wish to explore these features in
  2390. more detail. As far as we are aware, the Acegi Security implementation
  2391. does comply with the minimum standards of this RFC.</para>
  2392. </sect2>
  2393. <sect2 id="security-ui-anonymous">
  2394. <title>Anonymous Authentication</title>
  2395. <para>Particularly in the case of web request URI security, sometimes
  2396. it is more convenient to assign configuration attributes against every
  2397. possible secure object invocation. Put differently, sometimes it is
  2398. nice to say <literal>ROLE_SOMETHING</literal> is required by default
  2399. and only allow certain exceptions to this rule, such as for login,
  2400. logout and home pages of an application. There are also other
  2401. situations where anonymous authentication would be desired, such as
  2402. when an auditing interceptor queries the
  2403. <literal>ContextHolder</literal> to identify which principal was
  2404. responsible for a given operation. Such classes can be authored with
  2405. more robustness if they know the <literal>ContextHolder</literal>
  2406. always contains an <literal>Authentication</literal> object, and never
  2407. <literal>null</literal>.</para>
  2408. <para>Acegi Security provides three classes that together provide an
  2409. anoymous authentication feature.
  2410. <literal>AnonymousAuthenticationToken</literal> is an implementation
  2411. of <literal>Authentication</literal>, and stores the
  2412. <literal>GrantedAuthority</literal>[]s which apply to the anonymous
  2413. principal. There is a corresponding
  2414. <literal>AnonymousAuthenticationProvider</literal>, which is chained
  2415. into the <literal>ProviderManager</literal> so that
  2416. <literal>AnonymousAuthenticationTokens</literal> are accepted.
  2417. Finally, there is an AnonymousProcessingFilter, which is chained after
  2418. the normal authentication mechanisms and automatically add an
  2419. <literal>AnonymousAuthenticationToken</literal> to the
  2420. <literal>ContextHolder</literal> if there is no existing
  2421. <literal>Authentication</literal> held there. The definition of the
  2422. filter and authentication provider appears as follows:</para>
  2423. <para><programlisting>&lt;bean id="anonymousProcessingFilter" class="net.sf.acegisecurity.providers.anonymous.AnonymousProcessingFilter"&gt;
  2424. &lt;property name="key"&gt;&lt;value&gt;foobar&lt;/value&gt;&lt;/property&gt;
  2425. &lt;property name="userAttribute"&gt;&lt;value&gt;anonymousUser,ROLE_ANONYMOUS&lt;/value&gt;&lt;/property&gt;
  2426. &lt;/bean&gt;
  2427. &lt;bean id="anonymousAuthenticationProvider" class="net.sf.acegisecurity.providers.anonymous.AnonymousAuthenticationProvider"&gt;
  2428. &lt;property name="key"&gt;&lt;value&gt;foobar&lt;/value&gt;&lt;/property&gt;
  2429. &lt;/bean&gt;</programlisting></para>
  2430. <para>The <literal>key</literal> is shared between the filter and
  2431. authentication provider, so that tokens created by the former are
  2432. accepted by the latter. The <literal>userAttribute</literal> is
  2433. expressed in the form of
  2434. <literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>.
  2435. This is the same syntax as used after the equals sign for
  2436. <literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal>
  2437. property.</para>
  2438. <para>As explained earlier, the benefit of anonymous authentication is
  2439. that all URI patterns can have security applied to them. For
  2440. example:</para>
  2441. <para><programlisting>&lt;bean id="filterInvocationInterceptor" class="net.sf.acegisecurity.intercept.web.FilterSecurityInterceptor"&gt;
  2442. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  2443. &lt;property name="accessDecisionManager"&gt;&lt;ref local="httpRequestAccessDecisionManager"/&gt;&lt;/property&gt;
  2444. &lt;property name="objectDefinitionSource"&gt;
  2445. &lt;value&gt;
  2446. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  2447. PATTERN_TYPE_APACHE_ANT
  2448. /index.jsp=ROLE_ANONYMOUS,ROLE_USER
  2449. /hello.htm=ROLE_ANONYMOUS,ROLE_USER
  2450. /logoff.jsp=ROLE_ANONYMOUS,ROLE_USER
  2451. /acegilogin.jsp*=ROLE_ANONYMOUS,ROLE_USER
  2452. /**=ROLE_USER
  2453. &lt;/value&gt;
  2454. &lt;/property&gt;
  2455. &lt;/bean&gt;</programlisting>Rounding out the anonymous authentication
  2456. discussion is the <literal>AuthenticationTrustResolver</literal>
  2457. interface, with its corresponding
  2458. <literal>AuthenticationTrustResolverImpl</literal> implementation.
  2459. This interface provides an
  2460. <literal>isAnonymous(Authentication)</literal> method, which allows
  2461. interested classes to take into account this special type of
  2462. authentication status. The
  2463. <literal>SecurityEnforcementFilter</literal> uses this interface in
  2464. processing <literal>AccessDeniedException</literal>s. If an
  2465. <literal>AccessDeniedException</literal> is thrown, and the
  2466. authentication is of an anonymous type, instead of throwing a 403
  2467. (forbidden) response, the filter will instead commence the
  2468. <literal>AuthenticationEntryPoint</literal> so the principal can
  2469. authenticate properly. This is a necessary distinction, otherwise
  2470. principals would always be deemed "authenticated" and never be given
  2471. an opportunity to login via form, basic, digest or some other normal
  2472. authentication mechanism.</para>
  2473. </sect2>
  2474. <sect2 id="security-ui-remember-me">
  2475. <title>Remember-Me Authentication</title>
  2476. <para>Remember-me authentication refers to web sites being able to
  2477. remember the identity of a principal between sessions. This is
  2478. typically accomplished by sending a cookie to the browser, with the
  2479. cookie being detected during future sessions and causing automated
  2480. login to take place. Acegi Security provides the necessary hooks so
  2481. that such operations can take place, along with providing a concrete
  2482. implementation that uses hashing to preserve the security of
  2483. cookie-based tokens.</para>
  2484. <para>Remember-me authentication is not used with digest or basic
  2485. authentication, given they are often not used with
  2486. <literal>HttpSession</literal>s. Remember-me is used with
  2487. <literal>AuthenticationProcessingFilter</literal>, and is implemented
  2488. via hooks in the <literal>AbstractProcessingFilter</literal>
  2489. superclass. The hooks will invoke a concrete
  2490. <literal>RememberMeServices</literal> at the appropriate times. The
  2491. interface looks like this:</para>
  2492. <para><programlisting>public Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
  2493. public void loginFail(HttpServletRequest request, HttpServletResponse response);
  2494. public void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication);</programlisting></para>
  2495. <para>Please refer to JavaDocs for a fuller discussion on what the
  2496. methods do, although note at this stage
  2497. <literal>AbstractProcessingFilter</literal> only calls the
  2498. <literal>loginFail()</literal> and <literal>loginSuccess()</literal>
  2499. methods. The <literal>autoLogin()</literal> method is called by
  2500. <literal>RememberMeProcessingFilter</literal> whenever the
  2501. <literal>ContextHolder</literal> does not contain an
  2502. <literal>Authentication</literal>. This interface therefore provides
  2503. the underlaying remember-me implementation with sufficient
  2504. notification of authentication-related events, and delegates to the
  2505. implementation whenever a candidate web request might contain a cookie
  2506. and wish to be remembered.</para>
  2507. <para>This design allows any number of remember-me implementation
  2508. strategies. In the interests of simplicity and avoiding the need for
  2509. DAO implementations that specify write and create methods, Acegi
  2510. Security's only concrete implementation,
  2511. <literal>TokenBasedRememberMeServices</literal>, uses hashing to
  2512. achieve a useful remember-me strategy. In essence a cookie is sent to
  2513. the browser upon successful interactive authentication, with that
  2514. cookie being composed as follows:</para>
  2515. <para><programlisting>base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key))
  2516. username: As identifiable to TokenBasedRememberMeServices.getAuthenticationDao()
  2517. password: That matches the relevant UserDetails retrieved from TokenBasedRememberMeServices.getAuthenticationDao()
  2518. expirationTime: The date and time when the remember-me token expires, expressed in milliseconds
  2519. key: A private key to prevent modification of the remember-me token
  2520. </programlisting></para>
  2521. <para>As such the remember-me token is valid only for the period
  2522. specified, and provided that the username, password and key does not
  2523. change. Notably, this has a potential security issue issue in that a
  2524. captured remember-me token will be usable from any user agent until
  2525. such time as the token expires. This is the same issue as with digest
  2526. authentication. If a principal is aware a token has been captured,
  2527. they can easily change their password and immediately invalidate all
  2528. remember-me tokens on issue. However, if more significant security is
  2529. needed a rolling token approach should be used (this would require a
  2530. database) or remember-me services should simply not be used.</para>
  2531. <para><literal>TokenBasedRememberMeServices</literal> generates a
  2532. <literal>RememberMeAuthenticationToken</literal>, which is processed
  2533. by <literal>RememberMeAuthenticationProvider</literal>. A
  2534. <literal>key</literal> is shared between this authentication provider
  2535. and the <literal>TokenBasedRememberMeServices</literal>. In addition,
  2536. <literal>TokenBasedRememberMeServices</literal> requires an
  2537. <literal>AuthenticationDao</literal> from which it can retrieve the
  2538. username and password for signature comparison purposes, and generate
  2539. the <literal>RememberMeAuthenticationToken</literal> to contain the
  2540. correct <literal>GrantedAuthority</literal>[]s. Some sort of logout
  2541. command should be provided by the application (typically via a JSP)
  2542. that invalidates the cookie upon user request. See the Contacts Sample
  2543. application's <literal>logout.jsp</literal> for an example.</para>
  2544. <para>The beans required in an application context to enable
  2545. remember-me services are as follows:</para>
  2546. <para><programlisting>&lt;bean id="rememberMeProcessingFilter" class="net.sf.acegisecurity.ui.rememberme.RememberMeProcessingFilter"&gt;
  2547. &lt;property name="rememberMeServices"&gt;&lt;ref local="rememberMeServices"/&gt;&lt;/property&gt;
  2548. &lt;/bean&gt;
  2549. &lt;bean id="rememberMeServices" class="net.sf.acegisecurity.ui.rememberme.TokenBasedRememberMeServices"&gt;
  2550. &lt;property name="authenticationDao"&gt;&lt;ref local="jdbcDaoImpl"/&gt;&lt;/property&gt;
  2551. &lt;property name="key"&gt;&lt;value&gt;springRocks&lt;/value&gt;&lt;/property&gt;
  2552. &lt;/bean&gt;
  2553. &lt;bean id="rememberMeAuthenticationProvider" class="net.sf.acegisecurity.providers.rememberme.RememberMeAuthenticationProvider"&gt;
  2554. &lt;property name="key"&gt;&lt;value&gt;springRocks&lt;/value&gt;&lt;/property&gt;
  2555. &lt;/bean&gt;</programlisting>Don't forget to add your
  2556. <literal>RememberMeServices</literal> implementation to your
  2557. <literal>AuthenticationProcessingFilter.setRememberMeServices()</literal>
  2558. property, include the
  2559. <literal>RememberMeAuthenticationProvider</literal> in your
  2560. <literal>AuthenticationManager.setProviders()</literal> list, and add
  2561. a call to <literal>RememberMeProcessingFilter</literal> into your
  2562. <literal>FilterChainProxy</literal> (typically immediately after your
  2563. <literal>AuthenticationProcessingFilter</literal>).</para>
  2564. </sect2>
  2565. <sect2 id="security-ui-well-known">
  2566. <title>Well-Known Locations</title>
  2567. <para>Prior to release 0.8.0, Acegi Security referred to "well-known
  2568. locations" in discussions about storing the
  2569. <literal>Authentication</literal>. This approach did not explicitly
  2570. separate the function of <literal>HttpSession</literal> storage of
  2571. <literal>ContextHolder</literal> contents from the processing of
  2572. authentication requests received through various protocols. In
  2573. addition, the previous approach did not facilitate storage of
  2574. non-<literal>Authentication</literal> objects between requests, which
  2575. was limiting usefulness of the <literal>ContextHolder</literal> system
  2576. to member of the community. For these reasons, the notion of
  2577. well-known locations was abandoned, the
  2578. <literal>HttpSessionContextIntegrationFilter</literal> was
  2579. established, and the purpose of authentication processing mechanisms
  2580. was explicitly defined and limited to interaction with the
  2581. <literal>ContextHolder</literal> only. There is no need to refer to
  2582. well-known locations any more and we hope this clearer separation of
  2583. responsibilities enhances understanding of the project.</para>
  2584. </sect2>
  2585. </sect1>
  2586. <sect1 id="security-container-adapters">
  2587. <title>Container Adapters</title>
  2588. <sect2 id="security-container-adapters-overview">
  2589. <title>Overview</title>
  2590. <para>Very early versions of the Acegi Security System for Spring
  2591. exclusively used Container Adapters for interfacing authentication
  2592. with end users. Whilst this worked well, it required considerable time
  2593. to support multiple container versions and the configuration itself
  2594. was relatively time-consuming for developers. For this reason the HTTP
  2595. Form Authentication and HTTP Basic Authentication approaches were
  2596. developed, and are today recommended for almost all
  2597. applications.</para>
  2598. <para>Container Adapters enable the Acegi Security System for Spring
  2599. to integrate directly with the containers used to host end user
  2600. applications. This integration means that applications can continue to
  2601. leverage the authentication and authorization capabilities built into
  2602. containers (such as <literal>isUserInRole()</literal> and form-based
  2603. or basic authentication), whilst benefiting from the enhanced security
  2604. interception capabilities provided by the Acegi Security System for
  2605. Spring (it should be noted that Acegi Security also offers
  2606. <literal>ContextHolderAwareRequestWrapper</literal> to deliver
  2607. <literal>isUserInRole()</literal> and similar Servlet Specification
  2608. compatibility methods).</para>
  2609. <para>The integration between a container and the Acegi Security
  2610. System for Spring is achieved through an adapter. The adapter provides
  2611. a container-compatible user authentication provider, and needs to
  2612. return a container-compatible user object.</para>
  2613. <para>The adapter is instantiated by the container and is defined in a
  2614. container-specific configuration file. The adapter then loads a Spring
  2615. application context which defines the normal authentication manager
  2616. settings, such as the authentication providers that can be used to
  2617. authenticate the request. The application context is usually named
  2618. <literal>acegisecurity.xml</literal> and is placed in a
  2619. container-specific location.</para>
  2620. <para>The Acegi Security System for Spring currently supports Jetty,
  2621. Catalina (Tomcat), JBoss and Resin. Additional container adapters can
  2622. easily be written.</para>
  2623. </sect2>
  2624. <sect2 id="security-container-adapters-adapter-provider">
  2625. <title>Adapter Authentication Provider</title>
  2626. <para>As is always the case, the container adapter generated
  2627. <literal>Authentication</literal> object still needs to be
  2628. authenticated by an <literal>AuthenticationManager</literal> when
  2629. requested to do so by the
  2630. <literal>AbstractSecurityInterceptor</literal>. The
  2631. <literal>AuthenticationManager</literal> needs to be certain the
  2632. adapter-provided <literal>Authentication</literal> object is valid and
  2633. was actually authenticated by a trusted adapter.</para>
  2634. <para>Adapters create <literal>Authentication</literal> objects which
  2635. are immutable and implement the <literal>AuthByAdapter</literal>
  2636. interface. These objects store the hash of a key that is defined by
  2637. the adapter. This allows the <literal>Authentication</literal> object
  2638. to be validated by the <literal>AuthByAdapterProvider</literal>. This
  2639. authentication provider is defined as follows:</para>
  2640. <para><programlisting>&lt;bean id="authByAdapterProvider" class="net.sf.acegisecurity.adapters.AuthByAdapterProvider"&gt;
  2641. &lt;property name="key"&gt;&lt;value&gt;my_password&lt;/value&gt;&lt;/property&gt;
  2642. &lt;/bean&gt;</programlisting></para>
  2643. <para>The key must match the key that is defined in the
  2644. container-specific configuration file that starts the adapter. The
  2645. <literal>AuthByAdapterProvider</literal> automatically accepts as
  2646. valid any <literal>AuthByAdapter</literal> implementation that returns
  2647. the expected hash of the key.</para>
  2648. <para>To reiterate, this means the adapter will perform the initial
  2649. authentication using providers such as
  2650. <literal>DaoAuthenticationProvider</literal>, returning an
  2651. <literal>AuthByAdapter</literal> instance that contains a hash code of
  2652. the key. Later, when an application calls a security interceptor
  2653. managed resource, the <literal>AuthByAdapter</literal> instance in the
  2654. <literal>SecureContext</literal> in the
  2655. <literal>ContextHolder</literal> will be tested by the application's
  2656. <literal>AuthByAdapterProvider</literal>. There is no requirement for
  2657. additional authentication providers such as
  2658. <literal>DaoAuthenticationProvider</literal> within the
  2659. application-specific application context, as the only type of
  2660. <literal>Authentication</literal> instance that will be presented by
  2661. the application is from the container adapter.</para>
  2662. <para>Classloader issues are frequent with containers and the use of
  2663. container adapters illustrates this further. Each container requires a
  2664. very specific configuration. The installation instructions are
  2665. provided below. Once installed, please take the time to try the sample
  2666. application to ensure your container adapter is properly
  2667. configured.</para>
  2668. <para>When using container adapters with the
  2669. <literal>DaoAuthenticationProvider</literal>, ensure you set its
  2670. <literal>forcePrincipalAsString</literal> property to
  2671. <literal>true</literal>.</para>
  2672. </sect2>
  2673. <sect2 id="security-container-adapters-catalina">
  2674. <title>Catalina (Tomcat) Installation</title>
  2675. <para>The following was tested with Jakarta Tomcat 4.1.30 and
  2676. 5.0.19.</para>
  2677. <para><literal>$CATALINA_HOME</literal> refers to the root of your
  2678. Catalina (Tomcat) installation.</para>
  2679. <para>Edit your <literal>$CATALINA_HOME/conf/server.xml</literal> file
  2680. so the <literal>&lt;Engine&gt;</literal> section contains only one
  2681. active <literal>&lt;Realm&gt;</literal> entry. An example realm
  2682. entry:</para>
  2683. <para><programlisting> &lt;Realm className="net.sf.acegisecurity.adapters.catalina.CatalinaAcegiUserRealm"
  2684. appContextLocation="conf/acegisecurity.xml"
  2685. key="my_password" /&gt;</programlisting></para>
  2686. <para>Be sure to remove any other <literal>&lt;Realm&gt;</literal>
  2687. entry from your <literal>&lt;Engine&gt;</literal> section.</para>
  2688. <para>Copy <literal>acegisecurity.xml</literal> into
  2689. <literal>$CATALINA_HOME/conf</literal>.</para>
  2690. <para>Copy <literal>acegi-security-catalina-XX.jar</literal> into
  2691. <literal>$CATALINA_HOME/server/lib</literal>.</para>
  2692. <para>Copy the following files into
  2693. <literal>$CATALINA_HOME/common/lib</literal>:</para>
  2694. <itemizedlist>
  2695. <listitem>
  2696. <para><literal>aopalliance.jar</literal></para>
  2697. </listitem>
  2698. <listitem>
  2699. <para><literal>spring.jar</literal></para>
  2700. </listitem>
  2701. <listitem>
  2702. <para><literal>commons-codec.jar</literal></para>
  2703. </listitem>
  2704. <listitem>
  2705. <para><literal>burlap.jar</literal></para>
  2706. </listitem>
  2707. <listitem>
  2708. <para><literal>hessian.jar</literal></para>
  2709. </listitem>
  2710. </itemizedlist>
  2711. <para>None of the above JAR files (or
  2712. <literal>acegi-security-XX.jar</literal>) should be in your
  2713. application's <literal>WEB-INF/lib</literal>. The realm name indicated
  2714. in your <literal>web.xml</literal> does not matter with
  2715. Catalina.</para>
  2716. <para>We have received reports of problems using this Container
  2717. Adapter with Mac OS X. A work-around is to use a script such as
  2718. follows:</para>
  2719. <para><programlisting>#!/bin/sh
  2720. export CATALINA_HOME="/Library/Tomcat"
  2721. export JAVA_HOME="/Library/Java/Home"
  2722. cd /
  2723. $CATALINA_HOME/bin/startup.sh</programlisting></para>
  2724. </sect2>
  2725. <sect2 id="security-container-adapters-jetty">
  2726. <title>Jetty Installation</title>
  2727. <para>The following was tested with Jetty 4.2.18.</para>
  2728. <para><literal>$JETTY_HOME</literal> refers to the root of your Jetty
  2729. installation.</para>
  2730. <para>Edit your <literal>$JETTY_HOME/etc/jetty.xml</literal> file so
  2731. the <literal>&lt;Configure class&gt;</literal> section has a new
  2732. addRealm call:</para>
  2733. <para><programlisting> &lt;Call name="addRealm"&gt;
  2734. &lt;Arg&gt;
  2735. &lt;New class="net.sf.acegisecurity.adapters.jetty.JettyAcegiUserRealm"&gt;
  2736. &lt;Arg&gt;Spring Powered Realm&lt;/Arg&gt;
  2737. &lt;Arg&gt;my_password&lt;/Arg&gt;
  2738. &lt;Arg&gt;etc/acegisecurity.xml&lt;/Arg&gt;
  2739. &lt;/New&gt;
  2740. &lt;/Arg&gt;
  2741. &lt;/Call&gt;</programlisting></para>
  2742. <para>Copy <literal>acegisecurity.xml</literal> into
  2743. <literal>$JETTY_HOME/etc</literal>.</para>
  2744. <para>Copy the following files into
  2745. <literal>$JETTY_HOME/ext</literal>:<itemizedlist>
  2746. <listitem>
  2747. <para><literal>aopalliance.jar</literal></para>
  2748. </listitem>
  2749. <listitem>
  2750. <para><literal>commons-logging.jar</literal></para>
  2751. </listitem>
  2752. <listitem>
  2753. <para><literal>spring.jar</literal></para>
  2754. </listitem>
  2755. <listitem>
  2756. <para><literal>acegi-security-jetty-XX.jar</literal></para>
  2757. </listitem>
  2758. <listitem>
  2759. <para><literal>commons-codec.jar</literal></para>
  2760. </listitem>
  2761. <listitem>
  2762. <para><literal>burlap.jar</literal></para>
  2763. </listitem>
  2764. <listitem>
  2765. <para><literal>hessian.jar</literal></para>
  2766. </listitem>
  2767. </itemizedlist></para>
  2768. <para>None of the above JAR files (or
  2769. <literal>acegi-security-XX.jar</literal>) should be in your
  2770. application's <literal>WEB-INF/lib</literal>. The realm name indicated
  2771. in your <literal>web.xml</literal> does matter with Jetty. The
  2772. <literal>web.xml</literal> must express the same
  2773. <literal>&lt;realm-name&gt;</literal> as your
  2774. <literal>jetty.xml</literal> (in the example above, "Spring Powered
  2775. Realm").</para>
  2776. </sect2>
  2777. <sect2 id="security-container-adapters-joss">
  2778. <title>JBoss Installation</title>
  2779. <para>The following was tested with JBoss 3.2.6.</para>
  2780. <para><literal>$JBOSS_HOME</literal> refers to the root of your JBoss
  2781. installation.</para>
  2782. <para>There are two different ways of making spring context available
  2783. to the Jboss integration classes.</para>
  2784. <para>The first approach is by editing your
  2785. <literal>$JBOSS_HOME/server/your_config/conf/login-config.xml</literal>
  2786. file so that it contains a new entry under the
  2787. <literal>&lt;Policy&gt;</literal> section:</para>
  2788. <para><programlisting> &lt;application-policy name = "SpringPoweredRealm"&gt;
  2789. &lt;authentication&gt;
  2790. &lt;login-module code = "net.sf.acegisecurity.adapters.jboss.JbossSpringLoginModule"
  2791. flag = "required"&gt;
  2792. &lt;module-option name = "appContextLocation"&gt;acegisecurity.xml&lt;/module-option&gt;
  2793. &lt;module-option name = "key"&gt;my_password&lt;/module-option&gt;
  2794. &lt;/login-module&gt;
  2795. &lt;/authentication&gt;
  2796. &lt;/application-policy&gt;</programlisting></para>
  2797. <para>Copy <literal>acegisecurity.xml</literal> into
  2798. <literal>$JBOSS_HOME/server/your_config/conf</literal>.</para>
  2799. <para>In this configuration <literal>acegisecurity.xml</literal>
  2800. contains the spring context definition including all the
  2801. authentication manager beans. You have to bear in mind though, that
  2802. <literal>SecurityContext</literal> is created and destroyed on each
  2803. login request, so the login operation might become costly.
  2804. Alternatively, the second approach is to use Spring singleton
  2805. capabilities through
  2806. <literal>org.springframework.beans.factory.access.SingletonBeanFactoryLocator</literal>.
  2807. The required configuration for this approach is:</para>
  2808. <para><programlisting> &lt;application-policy name = "SpringPoweredRealm"&gt;
  2809. &lt;authentication&gt;
  2810. &lt;login-module code = "net.sf.acegisecurity.adapters.jboss.JbossSpringLoginModule"
  2811. flag = "required"&gt;
  2812. &lt;module-option name = "singletonId"&gt;springRealm&lt;/module-option&gt;
  2813. &lt;module-option name = "key"&gt;my_password&lt;/module-option&gt;
  2814. &lt;module-option name = "authenticationManager"&gt;authenticationManager&lt;/module-option&gt;
  2815. &lt;/login-module&gt;
  2816. &lt;/authentication&gt;
  2817. &lt;/application-policy&gt;</programlisting></para>
  2818. <para>In the above code fragment,
  2819. <literal>authenticationManager</literal> is a helper property that
  2820. defines the expected name of the
  2821. <literal>AuthenticationManager</literal> in case you have several
  2822. defined in the IoC container. The <literal>singletonId</literal>
  2823. property references a bean defined in a
  2824. <literal>beanRefFactory.xml</literal> file. This file needs to be
  2825. available from anywhere on the JBoss classpath, including
  2826. <literal>$JBOSS_HOME/server/your_config/conf</literal>. The
  2827. <literal>beanRefFactory.xml</literal> contains the following
  2828. declaration:</para>
  2829. <para><programlisting>&lt;beans&gt;
  2830. &lt;bean id="springRealm" singleton="true" lazy-init="true" class="org.springframework.context.support.ClassPathXmlApplicationContext"&gt;
  2831. &lt;constructor-arg&gt;
  2832. &lt;list&gt;
  2833. &lt;value&gt;acegisecurity.xml&lt;/value&gt;
  2834. &lt;/list&gt;
  2835. &lt;/constructor-arg&gt;
  2836. &lt;/bean&gt;
  2837. &lt;/beans&gt;</programlisting></para>
  2838. <para>Finally, irrespective of the configuration approach you need to
  2839. copy the following files into
  2840. <literal>$JBOSS_HOME/server/your_config/lib</literal>:<itemizedlist>
  2841. <listitem>
  2842. <para><literal>aopalliance.jar</literal></para>
  2843. </listitem>
  2844. <listitem>
  2845. <para><literal>spring.jar</literal></para>
  2846. </listitem>
  2847. <listitem>
  2848. <para><literal>acegi-security-jboss-XX.jar</literal></para>
  2849. </listitem>
  2850. <listitem>
  2851. <para><literal>commons-codec.jar</literal></para>
  2852. </listitem>
  2853. <listitem>
  2854. <para><literal>burlap.jar</literal></para>
  2855. </listitem>
  2856. <listitem>
  2857. <para><literal>hessian.jar</literal></para>
  2858. </listitem>
  2859. </itemizedlist></para>
  2860. <para>None of the above JAR files (or
  2861. <literal>acegi-security-XX.jar</literal>) should be in your
  2862. application's <literal>WEB-INF/lib</literal>. The realm name indicated
  2863. in your <literal>web.xml</literal> does not matter with JBoss.
  2864. However, your web application's
  2865. <literal>WEB-INF/jboss-web.xml</literal> must express the same
  2866. <literal>&lt;security-domain&gt;</literal> as your
  2867. <literal>login-config.xml</literal>. For example, to match the above
  2868. example, your <literal>jboss-web.xml</literal> would look like
  2869. this:</para>
  2870. <para><programlisting>&lt;jboss-web&gt;
  2871. &lt;security-domain&gt;java:/jaas/SpringPoweredRealm&lt;/security-domain&gt;
  2872. &lt;/jboss-web&gt;</programlisting></para>
  2873. </sect2>
  2874. <sect2 id="security-container-adapters-resin">
  2875. <title>Resin Installation</title>
  2876. <para>The following was tested with Resin 3.0.6.</para>
  2877. <para><literal>$RESIN_HOME</literal> refers to the root of your Resin
  2878. installation.</para>
  2879. <para>Resin provides several ways to support the container adapter. In
  2880. the instructions below we have elected to maximise consistency with
  2881. other container adapter configurations. This will allow Resin users to
  2882. simply deploy the sample application and confirm correct
  2883. configuration. Developers comfortable with Resin are naturally able to
  2884. use its capabilities to package the JARs with the web application
  2885. itself, and/or support single sign-on.</para>
  2886. <para>Copy the following files into
  2887. <literal>$RESIN_HOME/lib</literal>:<itemizedlist>
  2888. <listitem>
  2889. <para><literal>aopalliance.jar</literal></para>
  2890. </listitem>
  2891. <listitem>
  2892. <para><literal>commons-logging.jar</literal></para>
  2893. </listitem>
  2894. <listitem>
  2895. <para><literal>spring.jar</literal></para>
  2896. </listitem>
  2897. <listitem>
  2898. <para><literal>acegi-security-resin-XX.jar</literal></para>
  2899. </listitem>
  2900. <listitem>
  2901. <para><literal>commons-codec.jar</literal></para>
  2902. </listitem>
  2903. <listitem>
  2904. <para><literal>burlap.jar</literal></para>
  2905. </listitem>
  2906. <listitem>
  2907. <para><literal>hessian.jar</literal></para>
  2908. </listitem>
  2909. </itemizedlist></para>
  2910. <para>Unlike the container-wide <literal>acegisecurity.xml</literal>
  2911. files used by other container adapters, each Resin web application
  2912. will contain its own
  2913. <literal>WEB-INF/resin-acegisecurity.xml</literal> file. Each web
  2914. application will also contain a <literal>resin-web.xml</literal> file
  2915. which Resin uses to start the container adapter:</para>
  2916. <para><programlisting>&lt;web-app&gt;
  2917. &lt;authenticator&gt;
  2918. &lt;type&gt;net.sf.acegisecurity.adapters.resin.ResinAcegiAuthenticator&lt;/type&gt;
  2919. &lt;init&gt;
  2920. &lt;app-context-location&gt;WEB-INF/resin-acegisecurity.xml&lt;/app-context-location&gt;
  2921. &lt;key&gt;my_password&lt;/key&gt;
  2922. &lt;/init&gt;
  2923. &lt;/authenticator&gt;
  2924. &lt;/web-app&gt;</programlisting></para>
  2925. <para>With the basic configuration provided above, none of the JAR
  2926. files listed (or <literal>acegi-security-XX.jar</literal>) should be
  2927. in your application's <literal>WEB-INF/lib</literal>. The realm name
  2928. indicated in your <literal>web.xml</literal> does not matter with
  2929. Resin, as the relevant authentication class is indicated by the
  2930. <literal>&lt;authenticator&gt;</literal> setting.</para>
  2931. </sect2>
  2932. </sect1>
  2933. <sect1 id="security-cas">
  2934. <title>Yale Central Authentication Service (CAS) Single Sign On</title>
  2935. <sect2 id="security-cas-overview">
  2936. <title>Overview</title>
  2937. <para>Yale University produces an enterprise-wide single sign on
  2938. system known as CAS. Unlike other initiatives, Yale's Central
  2939. Authentication Service is open source, widely used, simple to
  2940. understand, platform independent, and supports proxy capabilities. The
  2941. Acegi Security System for Spring fully supports CAS, and provides an
  2942. easy migration path from single-application deployments of Acegi
  2943. Security through to multiple-application deployments secured by an
  2944. enterprise-wide CAS server.</para>
  2945. <para>You can learn more about CAS at
  2946. <literal>http://www.yale.edu/tp/auth/</literal>. You will need to
  2947. visit this URL to download the CAS Server files. Whilst the Acegi
  2948. Security System for Spring includes two CAS libraries in the
  2949. "-with-dependencies" ZIP file, you will still need the CAS Java Server
  2950. Pages and <literal>web.xml</literal> to customise and deploy your CAS
  2951. server.</para>
  2952. </sect2>
  2953. <sect2 id="security-cas-how-cas-works">
  2954. <title>How CAS Works</title>
  2955. <para>Whilst the CAS web site above contains two documents that detail
  2956. the architecture of CAS, we present the general overview again here
  2957. within the context of the Acegi Security System for Spring. The
  2958. following refers to CAS 2.0, being the version of CAS that Acegi
  2959. Security System for Spring supports.</para>
  2960. <para>Somewhere in your enterprise you will need to setup a CAS
  2961. server. The CAS server is simply a standard WAR file, so there isn't
  2962. anything difficult about setting up your server. Inside the WAR file
  2963. you will customise the login and other single sign on pages displayed
  2964. to users. You will also need to specify in the web.xml a
  2965. <literal>PasswordHandler</literal>. The
  2966. <literal>PasswordHandler</literal> has a simple method that returns a
  2967. boolean as to whether a given username and password is valid. Your
  2968. <literal>PasswordHandler</literal> implementation will need to link
  2969. into some type of backend authentication repository, such as an LDAP
  2970. server or database.</para>
  2971. <para>If you are already running an existing CAS server instance, you
  2972. will have already established a <literal>PasswordHandler</literal>. If
  2973. you do not already have a <literal>PasswordHandler</literal>, you
  2974. might prefer to use the Acegi Security System for Spring
  2975. <literal>CasPasswordHandler</literal> class. This class delegates
  2976. through to the standard Acegi Security
  2977. <literal>AuthenticationManager</literal>, enabling you to use a
  2978. security configuration you might already have in place. You do not
  2979. need to use the <literal>CasPasswordHandler</literal> class on your
  2980. CAS server if you do not wish. The Acegi Security System for Spring
  2981. will function as a CAS client successfully irrespective of the
  2982. <literal>PasswordHandler</literal> you've chosen for your CAS
  2983. server.</para>
  2984. <para>Apart from the CAS server itself, the other key player is of
  2985. course the secure web applications deployed throughout your
  2986. enterprise. These web applications are known as "services". There are
  2987. two types of services: standard services and proxy services. A proxy
  2988. service is able to request resources from other services on behalf of
  2989. the user. This will be explained more fully later.</para>
  2990. <para>Services can be developed in a large variety of languages, due
  2991. to CAS 2.0's very light XML-based protocol. The Yale CAS home page
  2992. contains a clients archive which demonstrates CAS clients in Java,
  2993. Active Server Pages, Perl, Python and others. Naturally, Java support
  2994. is very strong given the CAS server is written in Java. You do not
  2995. need to use any of CAS' client classes in applications secured by the
  2996. Acegi Security System for Spring. This is handled transparently for
  2997. you.</para>
  2998. <para>The basic interaction between a web browser, CAS server and an
  2999. Acegi Security for System Spring secured service is as follows:</para>
  3000. <orderedlist>
  3001. <listitem>
  3002. <para>The web user is browsing the service's public pages. CAS or
  3003. Acegi Security is not involved.</para>
  3004. </listitem>
  3005. <listitem>
  3006. <para>The user eventually requests a page that is either secure or
  3007. one of the beans it uses is secure. Acegi Security's
  3008. <literal>SecurityEnforcementFilter</literal> will detect the
  3009. <literal>AuthenticationException</literal>.</para>
  3010. </listitem>
  3011. <listitem>
  3012. <para>Because the user's <literal>Authentication</literal> object
  3013. (or lack thereof) caused an
  3014. <literal>AuthenticationException</literal>, the
  3015. <literal>SecurityEnforcementFilter</literal> will call the
  3016. configured <literal>AuthenticationEntryPoint</literal>. If using
  3017. CAS, this will be the
  3018. <literal>CasProcessingFilterEntryPoint</literal> class.</para>
  3019. </listitem>
  3020. <listitem>
  3021. <para>The <literal>CasProcessingFilterEntry</literal> point will
  3022. redirect the user's browser to the CAS server. It will also
  3023. indicate a <literal>service</literal> parameter, which is the
  3024. callback URL for the Acegi Security service. For example, the URL
  3025. to which the browser is redirected might be
  3026. <literal>https://my.company.com/cas/login?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check</literal>.</para>
  3027. </listitem>
  3028. <listitem>
  3029. <para>After the user's browser redirects to CAS, they will be
  3030. prompted for their username and password. If the user presents a
  3031. session cookie which indicates they've previously logged on, they
  3032. will not be prompted to login again (there is an exception to this
  3033. procedure, which we'll cover later). CAS will use the
  3034. <literal>PasswordHandler</literal> discussed above to decide
  3035. whether the username and password is valid.</para>
  3036. </listitem>
  3037. <listitem>
  3038. <para>Upon successful login, CAS will redirect the user's browser
  3039. back to the original service. It will also include a
  3040. <literal>ticket</literal> parameter, which is an opaque string
  3041. representing the "service ticket". Continuing our earlier example,
  3042. the URL the browser is redirected to might be
  3043. <literal>https://server3.company.com/webapp/j_acegi_cas_security_check?ticket=ST-0-ER94xMJmn6pha35CQRoZ</literal>.</para>
  3044. </listitem>
  3045. <listitem>
  3046. <para>Back in the service web application, the
  3047. <literal>CasProcessingFilter</literal> is always listening for
  3048. requests to <literal>/j_acegi_cas_security_check</literal> (this
  3049. is configurable, but we'll use the defaults in this introduction).
  3050. The processing filter will construct a
  3051. <literal>UsernamePasswordAuthenticationToken</literal>
  3052. representing the service ticket. The principal will be equal to
  3053. <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>,
  3054. whilst the credentials will be the service ticket opaque value.
  3055. This authentication request will then be handed to the configured
  3056. <literal>AuthenticationManager</literal>.</para>
  3057. </listitem>
  3058. <listitem>
  3059. <para>The <literal>AuthenticationManager</literal> implementation
  3060. will be the <literal>ProviderManager</literal>, which is in turn
  3061. configured with the <literal>CasAuthenticationProvider</literal>.
  3062. The <literal>CasAuthenticationProvider</literal> only responds to
  3063. <literal>UsernamePasswordAuthenticationToken</literal>s containing
  3064. the CAS-specific principal (such as
  3065. <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>)
  3066. and <literal>CasAuthenticationToken</literal>s (discussed
  3067. later).</para>
  3068. </listitem>
  3069. <listitem>
  3070. <para><literal>CasAuthenticationProvider</literal> will validate
  3071. the service ticket using a <literal>TicketValidator</literal>
  3072. implementation. Acegi Security includes one implementation, the
  3073. <literal>CasProxyTicketValidator</literal>. This implementation a
  3074. ticket validation class included in the CAS client library. The
  3075. <literal>CasProxyTicketValidator</literal> makes a HTTPS request
  3076. to the CAS server in order to validate the service ticket. The
  3077. <literal>CasProxyTicketValidator</literal> may also include a
  3078. proxy callback URL, which is included in this example:
  3079. <literal>https://my.company.com/cas/proxyValidate?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check&amp;ticket=ST-0-ER94xMJmn6pha35CQRoZ&amp;pgtUrl=https://server3.company.com/webapp/casProxy/receptor</literal>.</para>
  3080. </listitem>
  3081. <listitem>
  3082. <para>Back on the CAS server, the proxy validation request will be
  3083. received. If the presented service ticket matches the service URL
  3084. the ticket was issued to, CAS will provide an affirmative response
  3085. in XML indicating the username. If any proxy was involved in the
  3086. authentication (discussed below), the list of proxies is also
  3087. included in the XML response.</para>
  3088. </listitem>
  3089. <listitem>
  3090. <para>[OPTIONAL] If the request to the CAS validation service
  3091. included the proxy callback URL (in the <literal>pgtUrl</literal>
  3092. parameter), CAS will include a <literal>pgtIou</literal> string in
  3093. the XML response. This <literal>pgtIou</literal> represents a
  3094. proxy-granting ticket IOU. The CAS server will then create its own
  3095. HTTPS connection back to the <literal>pgtUrl</literal>. This is to
  3096. mutually authenticate the CAS server and the claimed service URL.
  3097. The HTTPS connection will be used to send a proxy granting ticket
  3098. to the original web application. For example,
  3099. <literal>https://server3.company.com/webapp/casProxy/receptor?pgtIou=PGTIOU-0-R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3vKB2SqSFFRnjPHt&amp;pgtId=PGT-1-si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpESZFArbaZiOKH</literal>.
  3100. We suggest you use CAS' <literal>ProxyTicketReceptor</literal>
  3101. servlet to receive these proxy-granting tickets, if they are
  3102. required.</para>
  3103. </listitem>
  3104. <listitem>
  3105. <para>The <literal>CasProxyTicketValidator</literal> will parse
  3106. the XML received from the CAS server. It will return to the
  3107. <literal>CasAuthenticationProvider</literal> a
  3108. <literal>TicketResponse</literal>, which includes the username
  3109. (mandatory), proxy list (if any were involved), and proxy-granting
  3110. ticket IOU (if the proxy callback was requested).</para>
  3111. </listitem>
  3112. <listitem>
  3113. <para>Next <literal>CasAuthenticationProvider</literal> will call
  3114. a configured <literal>CasProxyDecider</literal>. The
  3115. <literal>CasProxyDecider</literal> indicates whether the proxy
  3116. list in the <literal>TicketResponse</literal> is acceptable to the
  3117. service. Several implementations are provided with the Acegi
  3118. Security System: <literal>RejectProxyTickets</literal>,
  3119. <literal>AcceptAnyCasProxy</literal> and
  3120. <literal>NamedCasProxyDecider</literal>. These names are largely
  3121. self-explanatory, except <literal>NamedCasProxyDecider</literal>
  3122. which allows a <literal>List</literal> of trusted proxies to be
  3123. provided.</para>
  3124. </listitem>
  3125. <listitem>
  3126. <para><literal>CasAuthenticationProvider</literal> will next
  3127. request a <literal>CasAuthoritiesPopulator</literal> to advise the
  3128. <literal>GrantedAuthority</literal> objects that apply to the user
  3129. contained in the <literal>TicketResponse</literal>. Acegi Security
  3130. includes a <literal>DaoCasAuthoritiesPopulator</literal> which
  3131. simply uses the <literal>AuthenticationDao</literal>
  3132. infrastructure to find the <literal>UserDetails</literal> and
  3133. their associated <literal>GrantedAuthority</literal>s. Note that
  3134. the password and enabled/disabled status of
  3135. <literal>UserDetails</literal> returned by the
  3136. <literal>AuthenticationDao</literal> are ignored, as the CAS
  3137. server is responsible for authentication decisions.
  3138. <literal>DaoCasAuthoritiesPopulator</literal> is only concerned
  3139. with retrieving the <literal>GrantedAuthority</literal>s.</para>
  3140. </listitem>
  3141. <listitem>
  3142. <para>If there were no problems,
  3143. <literal>CasAuthenticationProvider</literal> constructs a
  3144. <literal>CasAuthenticationToken</literal> including the details
  3145. contained in the <literal>TicketResponse</literal> and the
  3146. <literal>GrantedAuthority</literal>s. The
  3147. <literal>CasAuthenticationToken</literal> contains the hash of a
  3148. key, so that the <literal>CasAuthenticationProvider</literal>
  3149. knows it created it.</para>
  3150. </listitem>
  3151. <listitem>
  3152. <para>Control then returns to
  3153. <literal>CasProcessingFilter</literal>, which places the created
  3154. <literal>CasAuthenticationToken</literal> into the
  3155. <literal>HttpSession</literal> attribute named
  3156. <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.</para>
  3157. </listitem>
  3158. <listitem>
  3159. <para>The user's browser is redirected to the original page that
  3160. caused the <literal>AuthenticationException</literal>.</para>
  3161. </listitem>
  3162. <listitem>
  3163. <para>As the <literal>Authentication</literal> object is now in
  3164. the well-known location, it is handled like any other
  3165. authentication approach. Usually the
  3166. <literal>HttpSessionIntegrationFilter</literal> will be used to
  3167. associate the <literal>Authentication</literal> object with the
  3168. <literal>ContextHolder</literal> for the duration of each
  3169. request.</para>
  3170. </listitem>
  3171. </orderedlist>
  3172. <para>It's good that you're still here! It might sound involved, but
  3173. you can relax as the Acegi Security System for Spring classes hide
  3174. much of the complexity. Let's now look at how this is
  3175. configured.</para>
  3176. </sect2>
  3177. <sect2 id="security-cas-install-server">
  3178. <title>CAS Server Installation (Optional)</title>
  3179. <para>As mentioned above, the Acegi Security System for Spring
  3180. includes a <literal>PasswordHandler</literal> that bridges your
  3181. existing <literal>AuthenticationManager</literal> into CAS. You do not
  3182. need to use this <literal>PasswordHandler</literal> to use Acegi
  3183. Security on the client side (any CAS
  3184. <literal>PasswordHandler</literal> will do).</para>
  3185. <para>To install, you will need to download and extract the CAS server
  3186. archive. We used version 2.0.12. There will be a
  3187. <literal>/web</literal> directory in the root of the deployment. Copy
  3188. an <literal>applicationContext.xml</literal> containing your
  3189. <literal>AuthenticationManager</literal> as well as the
  3190. <literal>CasPasswordHandler</literal> into the
  3191. <literal>/web/WEB-INF</literal> directory. A sample
  3192. <literal>applicationContext.xml</literal> is included below:</para>
  3193. <programlisting>&lt;bean id="inMemoryDaoImpl" class="net.sf.acegisecurity.providers.dao.memory.InMemoryDaoImpl"&gt;
  3194. &lt;property name="userMap"&gt;
  3195. &lt;value&gt;
  3196. marissa=koala,ROLES_IGNORED_BY_CAS
  3197. dianne=emu,ROLES_IGNORED_BY_CAS
  3198. scott=wombat,ROLES_IGNORED_BY_CAS
  3199. peter=opal,disabled,ROLES_IGNORED_BY_CAS
  3200. &lt;/value&gt;
  3201. &lt;/property&gt;
  3202. &lt;/bean&gt;
  3203. &lt;bean id="daoAuthenticationProvider" class="net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider"&gt;
  3204. &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
  3205. &lt;/bean&gt;
  3206. &lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
  3207. &lt;property name="providers"&gt;
  3208. &lt;list&gt;
  3209. &lt;ref bean="daoAuthenticationProvider"/&gt;
  3210. &lt;/list&gt;
  3211. &lt;/property&gt;
  3212. &lt;/bean&gt;
  3213. &lt;bean id="casPasswordHandler" class="net.sf.acegisecurity.adapters.cas.CasPasswordHandler"&gt;
  3214. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  3215. &lt;/bean&gt;</programlisting>
  3216. <para>Note the granted authorities are ignored by CAS because it has
  3217. no way of communicating the granted authorities to calling
  3218. applications. CAS is only concerned with username and passwords (and
  3219. the enabled/disabled status).</para>
  3220. <para>Next you will need to edit the existing
  3221. <literal>/web/WEB-INF/web.xml</literal> file. Add (or edit in the case
  3222. of the <literal>authHandler</literal> property) the following
  3223. lines:</para>
  3224. <para><programlisting>&lt;context-param&gt;
  3225. &lt;param-name&gt;edu.yale.its.tp.cas.authHandler&lt;/param-name&gt;
  3226. &lt;param-value&gt;net.sf.acegisecurity.adapters.cas.CasPasswordHandlerProxy&lt;/param-value&gt;
  3227. &lt;/context-param&gt;
  3228. &lt;context-param&gt;
  3229. &lt;param-name&gt;contextConfigLocation&lt;/param-name&gt;
  3230. &lt;param-value&gt;/WEB-INF/applicationContext.xml&lt;/param-value&gt;
  3231. &lt;/context-param&gt;
  3232. &lt;listener&gt;
  3233. &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
  3234. &lt;/listener&gt;</programlisting></para>
  3235. <para>Copy the <literal>spring.jar</literal> and
  3236. <literal>acegi-security.jar</literal> files into
  3237. <literal>/web/WEB-INF/lib</literal>. Now use the <literal>ant
  3238. dist</literal> task in the <literal>build.xml</literal> in the root of
  3239. the directory structure. This will create
  3240. <literal>/lib/cas.war</literal>, which is ready for deployment to your
  3241. servlet container.</para>
  3242. <para>Note CAS heavily relies on HTTPS. You can't even test the system
  3243. without a HTTPS certificate. Whilst you should refer to your web
  3244. container's documentation on setting up HTTPS, if you need some
  3245. additional help or a test certificate you might like to check the
  3246. <literal>samples/contacts/etc/ssl</literal> directory.</para>
  3247. </sect2>
  3248. <sect2 id="security-cas-install-client">
  3249. <title>CAS Acegi Security System Client Installation</title>
  3250. <para>The web application side of CAS is made easy due to the Acegi
  3251. Security System for Spring. It is assumed you already know the basics
  3252. of using the Acegi Security System for Spring, so these are not
  3253. covered again below. Only the CAS-specific beans are mentioned.</para>
  3254. <para>You will need to add a <literal>ServiceProperties</literal> bean
  3255. to your application context. This represents your service:</para>
  3256. <para><programlisting>&lt;bean id="serviceProperties" class="net.sf.acegisecurity.ui.cas.ServiceProperties"&gt;
  3257. &lt;property name="service"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/j_acegi_cas_security_check&lt;/value&gt;&lt;/property&gt;
  3258. &lt;property name="sendRenew"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
  3259. &lt;/bean&gt;</programlisting></para>
  3260. <para>The <literal>service</literal> must equal a URL that will be
  3261. monitored by the <literal>CasProcessingFilter</literal>. The
  3262. <literal>sendRenew</literal> defaults to false, but should be set to
  3263. true if your application is particularly sensitive. What this
  3264. parameter does is tell the CAS login service that a single sign on
  3265. login is unacceptable. Instead, the user will need to re-enter their
  3266. username and password in order to gain access to the service.</para>
  3267. <para>The following beans should be configured to commence the CAS
  3268. authentication process:</para>
  3269. <para><programlisting>&lt;bean id="casProcessingFilter" class="net.sf.acegisecurity.ui.cas.CasProcessingFilter"&gt;
  3270. &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
  3271. &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/casfailed.jsp&lt;/value&gt;&lt;/property&gt;
  3272. &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
  3273. &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_acegi_cas_security_check&lt;/value&gt;&lt;/property&gt;
  3274. &lt;/bean&gt;
  3275. &lt;bean id="securityEnforcementFilter" class="net.sf.acegisecurity.intercept.web.SecurityEnforcementFilter"&gt;
  3276. &lt;property name="filterSecurityInterceptor"&gt;&lt;ref bean="filterInvocationInterceptor"/&gt;&lt;/property&gt;
  3277. &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="casProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
  3278. &lt;/bean&gt;
  3279. &lt;bean id="casProcessingFilterEntryPoint" class="net.sf.acegisecurity.ui.cas.CasProcessingFilterEntryPoint"&gt;
  3280. &lt;property name="loginUrl"&gt;&lt;value&gt;https://localhost:8443/cas/login&lt;/value&gt;&lt;/property&gt;
  3281. &lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
  3282. &lt;/bean&gt;</programlisting></para>
  3283. <para>You will also need to add the
  3284. <literal>CasProcessingFilter</literal> to web.xml:</para>
  3285. <para><programlisting>&lt;filter&gt;
  3286. &lt;filter-name&gt;Acegi CAS Processing Filter&lt;/filter-name&gt;
  3287. &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
  3288. &lt;init-param&gt;
  3289. &lt;param-name&gt;targetClass&lt;/param-name&gt;
  3290. &lt;param-value&gt;net.sf.acegisecurity.ui.cas.CasProcessingFilter&lt;/param-value&gt;
  3291. &lt;/init-param&gt;
  3292. &lt;/filter&gt;
  3293. &lt;filter-mapping&gt;
  3294. &lt;filter-name&gt;Acegi CAS Processing Filter&lt;/filter-name&gt;
  3295. &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  3296. &lt;/filter-mapping&gt;</programlisting></para>
  3297. <para>The <literal>CasProcessingFilter</literal> has very similar
  3298. properties to the <literal>AuthenticationProcessingFilter</literal>
  3299. (used for form-based logins). Each property is
  3300. self-explanatory.</para>
  3301. <para>For CAS to operate, the
  3302. <literal>SecurityEnforcementFilter</literal> must have its
  3303. <literal>authenticationEntryPoint</literal> property set to the
  3304. <literal>CasProcessingFilterEntryPoint</literal> bean.</para>
  3305. <para>The <literal>CasProcessingFilterEntryPoint</literal> must refer
  3306. to the <literal>ServiceProperties</literal> bean (discussed above),
  3307. which provides the URL to the enterprise's CAS login server. This is
  3308. where the user's browser will be redirected.</para>
  3309. <para>Next you need to add an <literal>AuthenticationManager</literal>
  3310. that uses <literal>CasAuthenticationProvider</literal> and its
  3311. collaborators:</para>
  3312. <para><programlisting>&lt;bean id="authenticationManager" class="net.sf.acegisecurity.providers.ProviderManager"&gt;
  3313. &lt;property name="providers"&gt;
  3314. &lt;list&gt;
  3315. &lt;ref bean="casAuthenticationProvider"/&gt;
  3316. &lt;/list&gt;
  3317. &lt;/property&gt;
  3318. &lt;/bean&gt;
  3319. &lt;bean id="casAuthenticationProvider" class="net.sf.acegisecurity.providers.cas.CasAuthenticationProvider"&gt;
  3320. &lt;property name="casAuthoritiesPopulator"&gt;&lt;ref bean="casAuthoritiesPopulator"/&gt;&lt;/property&gt;
  3321. &lt;property name="casProxyDecider"&gt;&lt;ref bean="casProxyDecider"/&gt;&lt;/property&gt;
  3322. &lt;property name="ticketValidator"&gt;&lt;ref bean="casProxyTicketValidator"/&gt;&lt;/property&gt;
  3323. &lt;property name="statelessTicketCache"&gt;&lt;ref bean="statelessTicketCache"/&gt;&lt;/property&gt;
  3324. &lt;property name="key"&gt;&lt;value&gt;my_password_for_this_auth_provider_only&lt;/value&gt;&lt;/property&gt;
  3325. &lt;/bean&gt;
  3326. &lt;bean id="casProxyTicketValidator" class="net.sf.acegisecurity.providers.cas.ticketvalidator.CasProxyTicketValidator"&gt;
  3327. &lt;property name="casValidate"&gt;&lt;value&gt;https://localhost:8443/cas/proxyValidate&lt;/value&gt;&lt;/property&gt;
  3328. &lt;property name="proxyCallbackUrl"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/casProxy/receptor&lt;/value&gt;&lt;/property&gt;
  3329. &lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
  3330. &lt;!-- &lt;property name="trustStore"&gt;&lt;value&gt;/some/path/to/your/lib/security/cacerts&lt;/value&gt;&lt;/property&gt; --&gt;
  3331. &lt;/bean&gt;
  3332. &lt;bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"&gt;
  3333. &lt;property name="configLocation"&gt;
  3334. &lt;value&gt;classpath:/ehcache-failsafe.xml&lt;/value&gt;
  3335. &lt;/property&gt;
  3336. &lt;/bean&gt;
  3337. &lt;bean id="ticketCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean"&gt;
  3338. &lt;property name="cacheManager"&gt;
  3339. &lt;ref local="cacheManager"/&gt;
  3340. &lt;/property&gt;
  3341. &lt;property name="cacheName"&gt;
  3342. &lt;value&gt;ticketCache&lt;/value&gt;
  3343. &lt;/property&gt;
  3344. &lt;/bean&gt;
  3345. &lt;bean id="statelessTicketCache" class="net.sf.acegisecurity.providers.cas.cache.EhCacheBasedTicketCache"&gt;
  3346. &lt;property name="cache"&gt;&lt;ref local="ticketCacheBackend"/&gt;&lt;/property&gt;
  3347. &lt;/bean&gt;
  3348. &lt;bean id="casAuthoritiesPopulator" class="net.sf.acegisecurity.providers.cas.populator.DaoCasAuthoritiesPopulator"&gt;
  3349. &lt;property name="authenticationDao"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
  3350. &lt;/bean&gt;
  3351. &lt;bean id="casProxyDecider" class="net.sf.acegisecurity.providers.cas.proxy.RejectProxyTickets"/&gt;</programlisting></para>
  3352. <para>The beans are all reasonable self-explanatory if you refer back
  3353. to the "How CAS Works" section. Careful readers might notice one
  3354. surprise: the <literal>statelessTicketCache</literal> property of the
  3355. <literal>CasAuthenticationProvider</literal>. This is discussed in
  3356. detail in the "Advanced CAS Usage" section.</para>
  3357. <para>Note the <literal>CasProxyTicketValidator</literal> has a
  3358. remarked out <literal>trustStore</literal> property. This property
  3359. might be helpful if you experience HTTPS certificate issues. Also note
  3360. the <literal>proxyCallbackUrl</literal> is set so the service can
  3361. receive a proxy-granting ticket. As mentioned above, this is optional
  3362. and unnecessary if you do not require proxy-granting tickets. If you
  3363. do use this feature, you will need to configure a suitable servlet to
  3364. receive the proxy-granting tickets. We suggest you use CAS'
  3365. <literal>ProxyTicketReceptor</literal> by adding the following to your
  3366. web application's <literal>web.xml</literal>:</para>
  3367. <para><programlisting>&lt;servlet&gt;
  3368. &lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
  3369. &lt;servlet-class&gt;edu.yale.its.tp.cas.proxy.ProxyTicketReceptor&lt;/servlet-class&gt;
  3370. &lt;/servlet&gt;
  3371. &lt;servlet-mapping&gt;
  3372. &lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
  3373. &lt;url-pattern&gt;/casProxy/*&lt;/url-pattern&gt;
  3374. &lt;/servlet-mapping&gt;</programlisting></para>
  3375. <para>This completes the configuration of CAS. If you haven't made any
  3376. mistakes, your web application should happily work within the
  3377. framework of CAS single sign on. No other parts of the Acegi Security
  3378. System for Spring need to be concerned about the fact CAS handled
  3379. authentication.</para>
  3380. <para>There is also a <literal>contacts-cas.war</literal> file in the
  3381. sample applications directory. This sample application uses the above
  3382. settings and can be deployed to see CAS in operation.</para>
  3383. </sect2>
  3384. <sect2 id="security-cas-advanced-usage">
  3385. <title>Advanced CAS Usage</title>
  3386. <para>The <literal>CasAuthenticationProvider</literal> distinguishes
  3387. between stateful and stateless clients. A stateful client is
  3388. considered any that originates via the
  3389. <literal>CasProcessingFilter</literal>. A stateless client is any that
  3390. presents an authentication request via the
  3391. <literal>UsernamePasswordAuthenticationToken</literal> with a
  3392. principal equal to
  3393. <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>.</para>
  3394. <para>Stateless clients are likely to be via remoting protocols such
  3395. as Hessian and Burlap. The <literal>BasicProcessingFilter</literal> is
  3396. still used in this case, but the remoting protocol client is expected
  3397. to present a username equal to the static string above, and a password
  3398. equal to a CAS service ticket. Clients should acquire a CAS service
  3399. ticket directly from the CAS server.</para>
  3400. <para>Because remoting protocols have no way of presenting themselves
  3401. within the context of a <literal>HttpSession</literal>, it isn't
  3402. possible to rely on the <literal>HttpSession</literal>'s
  3403. <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>
  3404. attribute to locate the <literal>CasAuthenticationToken</literal>.
  3405. Furthermore, because the CAS server invalidates a service ticket after
  3406. it has been validated by the <literal>TicketValidator</literal>,
  3407. presenting the same service ticket on subsequent requests will not
  3408. work. It is similarly very difficult to obtain a proxy-granting ticket
  3409. for a remoting protocol client, as they are often deployed on client
  3410. machines which rarely have HTTPS URLs that would be accessible to the
  3411. CAS server.</para>
  3412. <para>One obvious option is to not use CAS at all for remoting
  3413. protocol clients. However, this would eliminate many of the desirable
  3414. features of CAS.</para>
  3415. <para>As a middle-ground, the
  3416. <literal>CasAuthenticationProvider</literal> uses a
  3417. <literal>StatelessTicketCache</literal>. This is used solely for
  3418. requests with a principal equal to
  3419. <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>. What
  3420. happens is the <literal>CasAuthenticationProvider</literal> will store
  3421. the resulting <literal>CasAuthenticationToken</literal> in the
  3422. <literal>StatelessTicketCache</literal>, keyed on the service ticket.
  3423. Accordingly, remoting protocol clients can present the same service
  3424. ticket and the <literal>CasAuthenticationProvider</literal> will not
  3425. need to contact the CAS server for validation (aside from the first
  3426. request).</para>
  3427. <para>The other aspect of advanced CAS usage involves creating proxy
  3428. tickets from the proxy-granting ticket. As indicated above, we
  3429. recommend you use CAS' <literal>ProxyTicketReceptor</literal> to
  3430. receive these tickets. The <literal>ProxyTicketReceptor</literal>
  3431. provides a static method that enables you to obtain a proxy ticket by
  3432. presenting the proxy-granting IOU ticket. You can obtain the
  3433. proxy-granting IOU ticket by calling
  3434. <literal>CasAuthenticationToken.getProxyGrantingTicketIou()</literal>.</para>
  3435. <para>It is hoped you find CAS integration easy and useful with the
  3436. Acegi Security System for Spring classes. Welcome to enterprise-wide
  3437. single sign on!</para>
  3438. </sect2>
  3439. </sect1>
  3440. <sect1 id="security-x509">
  3441. <title>X509 Authentication</title>
  3442. <sect2 id="security-x509-overview">
  3443. <title>Overview</title>
  3444. <para>The most common use of X509 certificate authentication is in
  3445. verifying the identity of a server when using SSL, most commonly when
  3446. using HTTPS from a browser. The browser will automatically check that
  3447. the certificate presented by a server has been issued (ie digitally
  3448. signed) by one of a list of trusted certificate authorities which it
  3449. maintains.</para>
  3450. <para>You can also use SSL with <quote>mutual authentication</quote>;
  3451. the server will then request a valid certificate from the client as
  3452. part of the SSL handshake. The server will authenticate the client by
  3453. checking that it's certificate is signed by an acceptable authority.
  3454. If a valid certificate has been provided, it can be obtained through
  3455. the servlet API in an application. The Acegi Security X509 module
  3456. extracts the certificate using a filter and passes it to the
  3457. configured X509 authentication provider to allow any additional
  3458. application-specific checks to be applied. It also maps the
  3459. certificate to an application user and loads that user's set of
  3460. granted authorities for use with the standard Acegi Security
  3461. infrastructure.</para>
  3462. <para>You should be familiar with using certificates and setting up
  3463. client authentication for your servlet container before attempting to
  3464. use it with Acegi Security. Most of the work is in creating and
  3465. installing suitable certificates and keys. For example, if you're
  3466. using Tomcat then read the instructions here <ulink
  3467. url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
  3468. It's important that you get this working before trying it out with
  3469. Acegi Security.</para>
  3470. </sect2>
  3471. <sect2 id="security-x509-details">
  3472. <title>X509 with Acegi Security</title>
  3473. <para>With X509 authentication, there is no explicit login procedure
  3474. so the implementation is relatively simple; there is no need to
  3475. redirect requests in order to interact with the user. As a result,
  3476. some of the classes behave slightly differently from their equivalents
  3477. in other packages. For example, the default <quote>entry point</quote>
  3478. class, which is normally responsible for starting the authentication
  3479. process, is only invoked if the certificate is rejected and it always
  3480. returns an error to the user. With a suitable bean configuration, the
  3481. normal sequence of events is as follows <orderedlist>
  3482. <listitem>
  3483. <para>The <classname>X509ProcessingFilter</classname> extracts
  3484. the certificate from the request and uses it as the credentials
  3485. for an authentication request. The generated authentication
  3486. request is an <classname>X509AuthenticationToken</classname>.
  3487. The request is passed to the authentication manager.</para>
  3488. </listitem>
  3489. <listitem>
  3490. <para>The <classname>X509AuthenticationProvider</classname>
  3491. receives the token. Its main concern is to obtain the user
  3492. information (in particular the user's granted authorities) that
  3493. matches the certificate. It delegates this responsibility to an
  3494. <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
  3495. </listitem>
  3496. .
  3497. <listitem>
  3498. <para>The populator's single method,
  3499. <methodname>getUserDetails(X509Certificate
  3500. userCertificate)</methodname> is invoked. Implementations should
  3501. return a <classname>UserDetails</classname> instance containing
  3502. the array of <classname>GrantedAuthority</classname> objects for
  3503. the user. This method can also choose to reject the certificate
  3504. (for example if it doesn't contain a matching user name). In
  3505. such cases it should throw a
  3506. <exceptionname>BadCredentialsException</exceptionname>. A
  3507. DAO-based implementation,
  3508. <classname>DaoX509AuthoritiesPopulator</classname>, is provided
  3509. which extracts the user's name from the subject <quote>common
  3510. name</quote> (CN) in the certificate. It also allows you to set
  3511. your own regular expression to match a different part of the
  3512. subject's distinguished name. An
  3513. <classname>AuthenticationDao</classname> is used to load the
  3514. user information.<!-- TODO: Give email matching as an example --></para>
  3515. </listitem>
  3516. <listitem>
  3517. <para>If everything has gone smoothly then there should be a
  3518. valid <classname>Authentication</classname> object in the secure
  3519. context and the invocation will procede as normal. If no
  3520. certificate was found, or the certificate was rejected, then the
  3521. <classname>SecurityEnforcementFilter</classname> will invoke the
  3522. <classname>X509ProcessingFilterEntryPoint</classname> which
  3523. returns a 403 error (forbidden) to the user.</para>
  3524. </listitem>
  3525. </orderedlist></para>
  3526. </sect2>
  3527. <sect2 id="security-x509-config">
  3528. <title>Configuring the X509 Provider</title>
  3529. <para>There is a version of the <link
  3530. linkend="security-sample">contacts sample application</link> which
  3531. uses X509. Copy the beans and filter setup from this as a starting
  3532. point for configuring your own application. A set of example
  3533. certificates is also included which you can use to configure your
  3534. server. These are <itemizedlist>
  3535. <listitem>
  3536. <para><filename>marissa.p12</filename>: A PKCS12 format file
  3537. containing the client key and certificate. These should be
  3538. installed in your browser. It maps to the user
  3539. <quote>marissa</quote> in the application.</para>
  3540. </listitem>
  3541. <listitem>
  3542. <para><filename>server.p12</filename>: The server certificate
  3543. and key for HTTPS connections.</para>
  3544. </listitem>
  3545. <listitem>
  3546. <para><filename>ca.jks</filename>: A Java keystore containing
  3547. the certificate for the authority which issued marissa's
  3548. certificate. This will be used by the container to validate
  3549. client certificates.</para>
  3550. </listitem>
  3551. </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
  3552. configuration in the <filename>server.xml</filename> file looks like
  3553. this <programlisting>&lt;!-- SSL/TLS Connector configuration --&gt;
  3554. &lt;Connector port="8443" address="${jboss.bind.address}"
  3555. maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
  3556. scheme="https" secure="true"
  3557. sslProtocol = "TLS"
  3558. clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
  3559. keystoreType="PKCS12" keystorePass="password"
  3560. truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
  3561. truststoreType="JKS" truststorePass="password"
  3562. /&gt;</programlisting><parameter>clientAuth</parameter> can also be set to
  3563. <parameter>want</parameter> if you still want SSL connections to
  3564. succeed even if the client doesn't provide a certificate. Obviously
  3565. these clients won't be able to access any objects secured by Acegi
  3566. Security (unless you use a non-X509 authentication mechanism, such as
  3567. BASIC authentication, to authenticate the user).</para>
  3568. </sect2>
  3569. </sect1>
  3570. <sect1 id="security-channels">
  3571. <title>Channel Security</title>
  3572. <sect2 id="security-channels-overview">
  3573. <title>Overview</title>
  3574. <para>In addition to coordinating the authentication and authorization
  3575. requirements of your application, the Acegi Security System for Spring
  3576. is also able to ensure unauthenticated web requests have certain
  3577. properties. These properties may include being of a particular
  3578. transport type, having a particular <literal>HttpSession</literal>
  3579. attribute set and so on. The most common requirement is for your web
  3580. requests to be received using a particular transport protocol, such as
  3581. HTTPS.</para>
  3582. <para>An important issue in considering transport security is that of
  3583. session hijacking. Your web container manages a
  3584. <literal>HttpSession</literal> by reference to a
  3585. <literal>jsessionid</literal> that is sent to user agents either via a
  3586. cookie or URL rewriting. If the <literal>jsessionid</literal> is ever
  3587. sent over HTTP, there is a possibility that session identifier can be
  3588. intercepted and used to impersonate the user after they complete the
  3589. authentication process. This is because most web containers maintain
  3590. the same session identifier for a given user, even after they switch
  3591. from HTTP to HTTPS pages.</para>
  3592. <para>If session hijacking is considered too significant a risk for
  3593. your particular application, the only option is to use HTTPS for every
  3594. request. This means the <literal>jsessionid</literal> is never sent
  3595. across an insecure channel. You will need to ensure your
  3596. <literal>web.xml</literal>-defined
  3597. <literal>&lt;welcome-file&gt;</literal> points to a HTTPS location,
  3598. and the application never directs the user to a HTTP location. The
  3599. Acegi Security System for Spring provides a solution to assist with
  3600. the latter.</para>
  3601. </sect2>
  3602. <sect2 id="security-channels-installation">
  3603. <title>Configuration</title>
  3604. <para>To utilise Acegi Security's channel security services, add the
  3605. following lines to <literal>web.xml</literal>:</para>
  3606. <para><programlisting>&lt;filter&gt;
  3607. &lt;filter-name&gt;Acegi Channel Processing Filter&lt;/filter-name&gt;
  3608. &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
  3609. &lt;init-param&gt;
  3610. &lt;param-name&gt;targetClass&lt;/param-name&gt;
  3611. &lt;param-value&gt;net.sf.acegisecurity.securechannel.ChannelProcessingFilter&lt;/param-value&gt;
  3612. &lt;/init-param&gt;
  3613. &lt;/filter&gt;
  3614. &lt;filter-mapping&gt;
  3615. &lt;filter-name&gt;Acegi Channel Processing Filter&lt;/filter-name&gt;
  3616. &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
  3617. &lt;/filter-mapping&gt;</programlisting></para>
  3618. <para>As usual when running <literal>FilterToBeanProxy</literal>, you
  3619. will also need to configure the filter in your application
  3620. context:</para>
  3621. <para><programlisting>&lt;bean id="channelProcessingFilter" class="net.sf.acegisecurity.securechannel.ChannelProcessingFilter"&gt;
  3622. &lt;property name="channelDecisionManager"&gt;&lt;ref bean="channelDecisionManager"/&gt;&lt;/property&gt;
  3623. &lt;property name="filterInvocationDefinitionSource"&gt;
  3624. &lt;value&gt;
  3625. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  3626. \A/secure/.*\Z=REQUIRES_SECURE_CHANNEL
  3627. \A/acegilogin.jsp.*\Z=REQUIRES_SECURE_CHANNEL
  3628. \A/j_acegi_security_check.*\Z=REQUIRES_SECURE_CHANNEL
  3629. \A.*\Z=REQUIRES_INSECURE_CHANNEL
  3630. &lt;/value&gt;
  3631. &lt;/property&gt;
  3632. &lt;/bean&gt;
  3633. &lt;bean id="channelDecisionManager" class="net.sf.acegisecurity.securechannel.ChannelDecisionManagerImpl"&gt;
  3634. &lt;property name="channelProcessors"&gt;
  3635. &lt;list&gt;
  3636. &lt;ref bean="secureChannelProcessor"/&gt;
  3637. &lt;ref bean="insecureChannelProcessor"/&gt;
  3638. &lt;/list&gt;
  3639. &lt;/property&gt;
  3640. &lt;/bean&gt;
  3641. &lt;bean id="secureChannelProcessor" class="net.sf.acegisecurity.securechannel.SecureChannelProcessor"/&gt;
  3642. &lt;bean id="insecureChannelProcessor" class="net.sf.acegisecurity.securechannel.InsecureChannelProcessor"/&gt;</programlisting></para>
  3643. <para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
  3644. style paths are also supported by the
  3645. <literal>ChannelProcessingFilter</literal>.</para>
  3646. <para>The <literal>ChannelProcessingFilter</literal> operates by
  3647. filtering all web requests and determining the configuration
  3648. attributes that apply. It then delegates to the
  3649. <literal>ChannelDecisionManager</literal>. The default implementation,
  3650. <literal>ChannelDecisionManagerImpl</literal>, should suffice in most
  3651. cases. It simply delegates through the list of configured
  3652. <literal>ChannelProcessor</literal> instances. A
  3653. <literal>ChannelProcessor</literal> will review the request, and if it
  3654. is unhappy with the request (eg it was received across the incorrect
  3655. transport protocol), it will perform a redirect, throw an exception or
  3656. take whatever other action is appropriate.</para>
  3657. <para>Included with the Acegi Security System for Spring are two
  3658. concrete <literal>ChannelProcessor</literal> implementations:
  3659. <literal>SecureChannelProcessor</literal> ensures requests with a
  3660. configuration attribute of <literal>REQUIRES_SECURE_CHANNEL</literal>
  3661. are received over HTTPS, whilst
  3662. <literal>InsecureChannelProcessor</literal> ensures requests with a
  3663. configuration attribute of
  3664. <literal>REQUIRES_INSECURE_CHANNEL</literal> are received over HTTP.
  3665. Both implementations delegate to a
  3666. <literal>ChannelEntryPoint</literal> if the required transport
  3667. protocol is not used. The two <literal>ChannelEntryPoint</literal>
  3668. implementations included with Acegi Security simply redirect the
  3669. request to HTTP and HTTPS as appropriate. Appropriate defaults are
  3670. assigned to the <literal>ChannelProcessor</literal> implementations
  3671. for the configuration attribute keywords they respond to and the
  3672. <literal>ChannelEntryPoint</literal> they delegate to, although you
  3673. have the ability to override these using the application
  3674. context.</para>
  3675. <para>Note that the redirections are absolute (eg
  3676. http://www.company.com:8080/app/page), not relative (eg /app/page).
  3677. During testing it was discovered that Internet Explorer 6 Service Pack
  3678. 1 has a bug whereby it does not respond correctly to a redirection
  3679. instruction which also changes the port to use. Accordingly, absolute
  3680. URLs are used in conjunction with bug detection logic in the
  3681. <literal>PortResolverImpl</literal> that is wired up by default to
  3682. many Acegi Security beans. Please refer to the JavaDocs for
  3683. <literal>PortResolverImpl</literal> for further details.</para>
  3684. </sect2>
  3685. <sect2 id="security-channels-usage">
  3686. <title>Usage</title>
  3687. <para>Once configured, using the channel security filter is very easy.
  3688. Simply request pages without regard to the protocol (ie HTTP or HTTPS)
  3689. or port (eg 80, 8080, 443, 8443 etc). Obviously you'll still need a
  3690. way of making the initial request (probably via the
  3691. <literal>web.xml</literal> <literal>&lt;welcome-file&gt;</literal> or
  3692. a well-known home page URL), but once this is done the filter will
  3693. perform redirects as defined by your application context.</para>
  3694. <para>You can also add your own <literal>ChannelProcessor</literal>
  3695. implementations to the <literal>ChannelDecisionManagerImpl</literal>.
  3696. For example, you might set a <literal>HttpSession</literal> attribute
  3697. when a human user is detected via a "enter the contents of this
  3698. graphic" procedure. Your <literal>ChannelProcessor</literal> would
  3699. respond to say <literal>REQUIRES_HUMAN_USER</literal> configuration
  3700. attributes and redirect to an appropriate entry point to start the
  3701. human user validation process if the <literal>HttpSession</literal>
  3702. attribute is not currently set.</para>
  3703. <para>To decide whether a security check belongs in a
  3704. <literal>ChannelProcessor</literal> or an
  3705. <literal>AccessDecisionVoter</literal>, remember that the former is
  3706. designed to handle unauthenticated requests, whilst the latter is
  3707. designed to handle authenticated requests. The latter therefore has
  3708. access to the granted authorities of the authenticated principal. In
  3709. addition, problems detected by a <literal>ChannelProcessor</literal>
  3710. will generally cause a HTTP/HTTPS redirection so its requirements can
  3711. be met, whilst problems detected by an
  3712. <literal>AccessDecisionVoter</literal> will ultimately result in an
  3713. <literal>AccessDeniedException</literal> (depending on the governing
  3714. <literal>AccessDecisionManager</literal>).</para>
  3715. </sect2>
  3716. </sect1>
  3717. <sect1 id="acls">
  3718. <title>Instance-Based Access Control List (ACL) Security</title>
  3719. <sect2 id="acls-overview">
  3720. <title>Overview</title>
  3721. <para>Complex applications often will find the need to define access
  3722. permissions not simply at a web request or method invocation level.
  3723. Instead, security decisions need to comprise both who
  3724. (<literal>Authentication</literal>), where
  3725. (<literal>MethodInvocation</literal>) and what
  3726. (<literal>SomeDomainObject</literal>). In other words, authorization
  3727. decisions also need to consider the actual domain object instance
  3728. subject of a method invocation.</para>
  3729. <para>Imagine you're designing an application for a pet clinic. There
  3730. will be two main groups of users of your Spring-based application:
  3731. staff of the pet clinic, as well as the pet clinic's customers. The
  3732. staff will have access to all of the data, whilst your customers will
  3733. only be able to see their own customer records. To make it a little
  3734. more interesting, your customers can allow other users to see their
  3735. customer records, such as their "puppy preschool "mentor or president
  3736. of their local "Pony Club". Using Acegi Security System for Spring as
  3737. the foundation, you have several approaches that can be
  3738. used:<orderedlist>
  3739. <listitem>
  3740. <para>Write your business methods to enforce the security. You
  3741. could consult a collection within the
  3742. <literal>Customer</literal> domain object instance to determine
  3743. which users have access. By using the
  3744. <literal>ContextHolder.getContext()</literal> and casting it to
  3745. <literal>SecureContext</literal>, you'll be able to access the
  3746. <literal>Authentication</literal> object.</para>
  3747. </listitem>
  3748. <listitem>
  3749. <para>Write an <literal>AccessDecisionVoter</literal> to enforce
  3750. the security from the <literal>GrantedAuthority[]</literal>s
  3751. stored in the <literal>Authentication</literal> object. This
  3752. would mean your <literal>AuthenticationManager</literal> would
  3753. need to populate the <literal>Authentication</literal> with
  3754. custom <literal>GrantedAuthority</literal>[]s representing each
  3755. of the <literal>Customer</literal> domain object instances the
  3756. principal has access to.</para>
  3757. </listitem>
  3758. <listitem>
  3759. <para>Write an <literal>AccessDecisionVoter</literal> to enforce
  3760. the security and open the target <literal>Customer</literal>
  3761. domain object directly. This would mean your voter needs access
  3762. to a DAO that allows it to retrieve the
  3763. <literal>Customer</literal> object. It would then access the
  3764. <literal>Customer</literal> object's collection of approved
  3765. users and make the appropriate decision.</para>
  3766. </listitem>
  3767. </orderedlist></para>
  3768. <para>Each one of these approaches is perfectly legitimate. However,
  3769. the first couples your authorization checking to your business code.
  3770. The main problems with this include the enhanced difficulty of unit
  3771. testing and the fact it would be more difficult to reuse the
  3772. <literal>Customer</literal> authorization logic elsewhere. Obtaining
  3773. the <literal>GrantedAuthority[]</literal>s from the
  3774. <literal>Authentication</literal> object is also fine, but will not
  3775. scale to large numbers of <literal>Customer</literal>s. If a user
  3776. might be able to access 5,000 <literal>Customer</literal>s (unlikely
  3777. in this case, but imagine if it were a popular vet for a large Pony
  3778. Club!) the amount of memory consumed and time required to construct
  3779. the <literal>Authentication</literal> object would be undesirable. The
  3780. final method, opening the <literal>Customer</literal> directly from
  3781. external code, is probably the best of the three. It achieves
  3782. separation of concerns, and doesn't misuse memory or CPU cycles, but
  3783. it is still inefficient in that both the
  3784. <literal>AccessDecisionVoter</literal> and the eventual business
  3785. method itself will perform a call to the DAO responsible for
  3786. retrieving the <literal>Customer</literal> object. Two accesses per
  3787. method invocation is clearly undesirable. In addition, with every
  3788. approach listed you'll need to write your own access control list
  3789. (ACL) persistence and business logic from scratch.</para>
  3790. <para>Fortunately, there is another alternative, which we'll talk
  3791. about below.</para>
  3792. </sect2>
  3793. <sect2 id="acls-acl-package">
  3794. <title>The net.sf.acegisecurity.acl Package</title>
  3795. <para>The <literal>net.sf.acegisecurity.acl</literal> package is very
  3796. simple, comprising only a handful of interfaces and a single class, as
  3797. shown in Figure 6. It provides the basic foundation for access control
  3798. list (ACL) lookups.</para>
  3799. <para><mediaobject>
  3800. <imageobject role="html">
  3801. <imagedata align="center" fileref="images/ACLSecurity.gif"
  3802. format="GIF" />
  3803. </imageobject>
  3804. <caption>
  3805. <para>Figure 6: Access Control List Manager</para>
  3806. </caption>
  3807. </mediaobject></para>
  3808. <para>The central interface is <literal>AclManager</literal>, which is
  3809. defined by two methods:</para>
  3810. <para><programlisting>public AclEntry[] getAcls(java.lang.Object domainInstance);
  3811. public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authentication);</programlisting></para>
  3812. <para><literal>AclManager</literal> is intended to be used as a
  3813. collaborator against your business objects, or, more desirably,
  3814. <literal>AccessDecisionVoter</literal>s. This means you use Spring's
  3815. normal <literal>ApplicationContext</literal> features to wire up your
  3816. <literal>AccessDecisionVoter</literal> (or business method) with an
  3817. <literal>AclManager</literal>. Consideration was given to placing the
  3818. ACL information in the <literal>ContextHolder</literal>, but it was
  3819. felt this would be inefficient both in terms of memory usage as well
  3820. as the time spent loading potentially unused ACL information. The
  3821. trade-off of needing to wire up a collaborator for those objects
  3822. requiring ACL information is rather minor, particularly in a
  3823. Spring-managed application.</para>
  3824. <para>The first method of the <literal>AclManager</literal> will
  3825. return all ACLs applying to the domain object instance passed to it.
  3826. The second method does the same, but only returns those ACLs which
  3827. apply to the passed <literal>Authentication</literal> object.</para>
  3828. <para>The <literal>AclEntry</literal> interface returned by
  3829. <literal>AclManager</literal> is merely a marker interface. You will
  3830. need to provide an implementation that reflects that ACL permissions
  3831. for your application.</para>
  3832. <para>Rounding out the <literal>net.sf.acegisecurity.acl</literal>
  3833. package is an <literal>AclProviderManager</literal> class, with a
  3834. corresponding <literal>AclProvider</literal> interface.
  3835. <literal>AclProviderManager</literal> is a concrete implementation of
  3836. <literal>AclManager</literal>, which iterates through registered
  3837. <literal>AclProvider</literal>s. The first
  3838. <literal>AclProvider</literal> that indicates it can authoritatively
  3839. provide ACL information for the presented domain object instance will
  3840. be used. This is very similar to the
  3841. <literal>AuthenticationProvider</literal> interface used for
  3842. authentication.</para>
  3843. <para>With this background, let's now look at a usable ACL
  3844. implementation.</para>
  3845. </sect2>
  3846. <sect2 id="acls-masking">
  3847. <title>Integer Masked ACLs</title>
  3848. <para>Acegi Security System for Spring includes a production-quality
  3849. ACL provider implementation, which is shown in Figure 7.</para>
  3850. <para><mediaobject>
  3851. <imageobject role="html">
  3852. <imagedata align="center" fileref="images/BasicAclProvider.gif"
  3853. format="GIF" />
  3854. </imageobject>
  3855. <caption>
  3856. <para>Figure 7: Basic ACL Manager</para>
  3857. </caption>
  3858. </mediaobject></para>
  3859. <para>The implementation is based on integer masking, which is
  3860. commonly used for ACL permissions given its flexibility and speed.
  3861. Anyone who has used Unix's <literal>chmod</literal> command will know
  3862. all about this type of permission masking (eg <literal>chmod
  3863. 777</literal>). You'll find the classes and interfaces for the integer
  3864. masking ACL package under
  3865. <literal>net.sf.acegisecurity.acl.basic</literal>.</para>
  3866. <para>Extending the <literal>AclEntry</literal> interface is a
  3867. <literal>BasicAclEntry</literal> interface, with the main methods
  3868. shown below:</para>
  3869. <para><programlisting>public AclObjectIdentity getAclObjectIdentity();
  3870. public AclObjectIdentity getAclObjectParentIdentity();
  3871. public int getMask();
  3872. public java.lang.Object getRecipient();</programlisting></para>
  3873. <para>As shown, each <literal>BasicAclEntry</literal> has four main
  3874. properties. The <literal>mask</literal> is the integer that represents
  3875. the permissions granted to the <literal>recipient</literal>. The
  3876. <literal>aclObjectIdentity</literal> is able to identify the domain
  3877. object instance for which the ACL applies, and the
  3878. <literal>aclObjectParentIdentity</literal> optionally specifies the
  3879. parent of the domain object instance. Multiple
  3880. <literal>BasicAclEntry</literal>s usually exist against a single
  3881. domain object instance, and as suggested by the parent identity
  3882. property, permissions granted higher in the object hierarchy will
  3883. trickle down and be inherited (unless blocked by integer zero).</para>
  3884. <para><literal>BasicAclEntry</literal> implementations typically
  3885. provide convenience methods, such as
  3886. <literal>isReadAllowed()</literal>, to avoid application classes
  3887. needing to perform bit masking themselves. The
  3888. <literal>SimpleAclEntry</literal> and
  3889. <literal>AbstractBasicAclEntry</literal> demonstrate and provide much
  3890. of this bit masking logic.</para>
  3891. <para>The <literal>AclObjectIdentity</literal> itself is merely a
  3892. marker interface, so you need to provide implementations for your
  3893. domain objects. However, the package does include a
  3894. <literal>NamedEntityObjectIdentity</literal> implementation which will
  3895. suit many needs. The <literal>NamedEntityObjectIdentity</literal>
  3896. identifies a given domain object instance by the classname of the
  3897. instance and the identity of the instance. A
  3898. <literal>NamedEntityObjectIdentity</literal> can be constructed
  3899. manually (by calling the constructor and providing the classname and
  3900. identity <literal>String</literal>s), or by passing in any domain
  3901. object that contains a <literal>getId()</literal> method.</para>
  3902. <para>The actual <literal>AclProvider</literal> implementation is
  3903. named <literal>BasicAclProvider</literal>. It has adopted a similar
  3904. design to that used by the authentication-related
  3905. <literal>DaoAuthenticationProvder</literal>. Specifically, you define
  3906. a <literal>BasicAclDao</literal> against the provider, so different
  3907. ACL repository types can be accessed in a pluggable manner. The
  3908. <literal>BasicAclProvider</literal> also supports pluggable cache
  3909. providers (with Acegi Security System for Spring including an
  3910. implementation that fronts EH-CACHE).</para>
  3911. <para>The <literal>BasicAclDao</literal> interface is very simple to
  3912. implement:</para>
  3913. <para><programlisting>public BasicAclEntry[] getAcls(AclObjectIdentity aclObjectIdentity);</programlisting></para>
  3914. <para>A <literal>BasicAclDao</literal> implementation needs to
  3915. understand the presented <literal>AclObjectIdentity</literal> and how
  3916. it maps to a storage repository, find the relevant records, and create
  3917. appropriate <literal>BasicAclEntry</literal> objects and return
  3918. them.</para>
  3919. <para>Acegi Security includes a single <literal>BasicAclDao</literal>
  3920. implementation called <literal>JdbcDaoImpl</literal>. As implied by
  3921. the name, <literal>JdbcDaoImpl</literal> accesses ACL information from
  3922. a JDBC database. There is also an extended version of this DAO,
  3923. <literal>JdbcExtendedDaoImpl</literal>, which provides CRUD operations
  3924. on the JDBC database, although we won't discuss these features here.
  3925. The default database schema and some sample data will aid in
  3926. understanding its function:</para>
  3927. <para><programlisting>CREATE TABLE acl_object_identity (
  3928. id IDENTITY NOT NULL,
  3929. object_identity VARCHAR_IGNORECASE(250) NOT NULL,
  3930. parent_object INTEGER,
  3931. acl_class VARCHAR_IGNORECASE(250) NOT NULL,
  3932. CONSTRAINT unique_object_identity UNIQUE(object_identity),
  3933. FOREIGN KEY (parent_object) REFERENCES acl_object_identity(id)
  3934. );
  3935. CREATE TABLE acl_permission (
  3936. id IDENTITY NOT NULL,
  3937. acl_object_identity INTEGER NOT NULL,
  3938. recipient VARCHAR_IGNORECASE(100) NOT NULL,
  3939. mask INTEGER NOT NULL,
  3940. CONSTRAINT unique_recipient UNIQUE(acl_object_identity, recipient),
  3941. FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity(id)
  3942. );
  3943. INSERT INTO acl_object_identity VALUES (1, 'corp.DomainObject:1', null, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3944. INSERT INTO acl_object_identity VALUES (2, 'corp.DomainObject:2', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3945. INSERT INTO acl_object_identity VALUES (3, 'corp.DomainObject:3', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3946. INSERT INTO acl_object_identity VALUES (4, 'corp.DomainObject:4', 1, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3947. INSERT INTO acl_object_identity VALUES (5, 'corp.DomainObject:5', 3, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3948. INSERT INTO acl_object_identity VALUES (6, 'corp.DomainObject:6', 3, 'net.sf.acegisecurity.acl.basic.SimpleAclEntry');
  3949. INSERT INTO acl_permission VALUES (null, 1, 'ROLE_SUPERVISOR', 1);
  3950. INSERT INTO acl_permission VALUES (null, 2, 'ROLE_SUPERVISOR', 0);
  3951. INSERT INTO acl_permission VALUES (null, 2, 'marissa', 2);
  3952. INSERT INTO acl_permission VALUES (null, 3, 'scott', 14);
  3953. INSERT INTO acl_permission VALUES (null, 6, 'scott', 1);</programlisting></para>
  3954. <para>As can be seen, database-specific constraints are used
  3955. extensively to ensure the integrity of the ACL information. If you
  3956. need to use a different database (Hypersonic SQL statements are shown
  3957. above), you should try to implement equivalent constraints.</para>
  3958. <para>The <literal>JdbcDaoImpl</literal> will only respond to requests
  3959. for <literal>NamedEntityObjectIdentity</literal>s. It converts such
  3960. identities into a single <literal>String</literal>, comprising
  3961. the<literal> NamedEntityObjectIdentity.getClassname()</literal> +
  3962. <literal>":"</literal> +
  3963. <literal>NamedEntityObjectIdentity.getId()</literal>. This yields the
  3964. type of <literal>object_identity</literal> values shown above. As
  3965. indicated by the sample data, each database row corresponds to a
  3966. single <literal>BasicAclEntry</literal>. As stated earlier and
  3967. demonstrated by <literal>corp.DomainObject:2</literal> in the above
  3968. sample data, each domain object instance will often have multiple
  3969. <literal>BasicAclEntry</literal>[]s.</para>
  3970. <para>As <literal>JdbcDaoImpl</literal> is required to return concrete
  3971. <literal>BasicAclEntry</literal> classes, it needs to know which
  3972. <literal>BasicAclEntry</literal> implementation it is to create and
  3973. populate. This is the role of the <literal>acl_class</literal> column.
  3974. <literal>JdbcDaoImpl</literal> will create the indicated class and set
  3975. its <literal>mask</literal>, <literal>recipient</literal>,
  3976. <literal>aclObjectIdentity</literal> and
  3977. <literal>aclObjectParentIdentity</literal> properties.</para>
  3978. <para>As you can probably tell from the sample data, the
  3979. <literal>parent_object_identity</literal> value can either be null or
  3980. in the same format as the <literal>object_identity</literal>. If
  3981. non-null, <literal>JdbcDaoImpl</literal> will create a
  3982. <literal>NamedEntityObjectIdentity</literal> to place inside the
  3983. returned <literal>BasicAclEntry</literal> class.</para>
  3984. <para>Returning to the <literal>BasicAclProvider</literal>, before it
  3985. can poll the <literal>BasicAclDao</literal> implementation it needs to
  3986. convert the domain object instance it was passed into an
  3987. <literal>AclObjectIdentity</literal>.
  3988. <literal>BasicAclProvider</literal> has a <literal>protected
  3989. AclObjectIdentity obtainIdentity(Object domainInstance)</literal>
  3990. method that is responsible for this. As a protected method, it enables
  3991. subclasses to easily override. The normal implementation checks
  3992. whether the passed domain object instance implements the
  3993. <literal>AclObjectIdentityAware</literal> interface, which is merely a
  3994. getter for an <literal>AclObjectIdentity</literal>. If the domain
  3995. object does implement this interface, that is the identity returned.
  3996. If the domain object does not implement this interface, the method
  3997. will attempt to create an <literal>AclObjectIdentity</literal> by
  3998. passing the domain object instance to the constructor of a class
  3999. defined by the
  4000. <literal>BasicAclProvider.getDefaultAclObjectIdentity()</literal>
  4001. method. By default the defined class is
  4002. <literal>NamedEntityObjectIdentity</literal>, which was described in
  4003. more detail above. Therefore, you will need to either (i) provide a
  4004. <literal>getId()</literal> method on your domain objects, (ii)
  4005. implement <literal>AclObjectIdentityAware</literal> on your domain
  4006. objects, (iii) provide an alternative
  4007. <literal>AclObjectIdentity</literal> implementation that will accept
  4008. your domain object in its constructor, or (iv) override the
  4009. <literal>obtainIdentity(Object)</literal> method.</para>
  4010. <para>Once the <literal>AclObjectIdentity</literal> of the domain
  4011. object instance is determined, the <literal>BasicAclProvider</literal>
  4012. will poll the DAO to obtain its <literal>BasicAclEntry</literal>[]s.
  4013. If any of the entries returned by the DAO indicate there is a parent,
  4014. that parent will be polled, and the process will repeat until there is
  4015. no further parent. The permissions assigned to a
  4016. <literal>recipient</literal> closest to the domain object instance
  4017. will always take priority and override any inherited permissions. From
  4018. the sample data above, the following inherited permissions would
  4019. apply:</para>
  4020. <para><programlisting>--- Mask integer 0 = no permissions
  4021. --- Mask integer 1 = administer
  4022. --- Mask integer 2 = read
  4023. --- Mask integer 6 = read and write permissions
  4024. --- Mask integer 14 = read and write and create permissions
  4025. ---------------------------------------------------------------------
  4026. --- *** INHERITED RIGHTS FOR DIFFERENT INSTANCES AND RECIPIENTS ***
  4027. --- INSTANCE RECIPIENT PERMISSION(S) (COMMENT #INSTANCE)
  4028. ---------------------------------------------------------------------
  4029. --- 1 ROLE_SUPERVISOR Administer
  4030. --- 2 ROLE_SUPERVISOR None (overrides parent #1)
  4031. --- marissa Read
  4032. --- 3 ROLE_SUPERVISOR Administer (from parent #1)
  4033. --- scott Read, Write, Create
  4034. --- 4 ROLE_SUPERVISOR Administer (from parent #1)
  4035. --- 5 ROLE_SUPERVISOR Administer (from parent #3)
  4036. --- scott Read, Write, Create (from parent #3)
  4037. --- 6 ROLE_SUPERVISOR Administer (from parent #3)
  4038. --- scott Administer (overrides parent #3)</programlisting></para>
  4039. <para>So the above explains how a domain object instance has its
  4040. <literal>AclObjectIdentity</literal> discovered, and the
  4041. <literal>BasicAclDao</literal> will be polled successively until an
  4042. array of inherited permissions is constructed for the domain object
  4043. instance. The final step is to determine the
  4044. <literal>BasicAclEntry</literal>[]s that are actually applicable to a
  4045. given <literal>Authentication</literal> object.</para>
  4046. <para>As you would recall, the <literal>AclManager</literal> (and all
  4047. delegates, up to and including <literal>BasicAclProvider</literal>)
  4048. provides a method which returns only those
  4049. <literal>BasicAclEntry</literal>[]s applying to a passed
  4050. <literal>Authentication</literal> object.
  4051. <literal>BasicAclProvider</literal> delivers this functionality by
  4052. delegating the filtering operation to an
  4053. <literal>EffectiveAclsResolver</literal> implementation. The default
  4054. implementation,
  4055. <literal>GrantedAuthorityEffectiveAclsResolver</literal>, will iterate
  4056. through the <literal>BasicAclEntry</literal>[]s and include only those
  4057. where the <literal>recipient</literal> is equal to either the
  4058. <literal>Authentication</literal>'s <literal>principal</literal> or
  4059. any of the <literal>Authentication</literal>'s
  4060. <literal>GrantedAuthority</literal>[]s. Please refer to the JavaDocs
  4061. for more information.</para>
  4062. <mediaobject>
  4063. <imageobject role="html">
  4064. <imagedata align="center" fileref="images/Permissions.gif"
  4065. format="GIF" />
  4066. </imageobject>
  4067. <caption>
  4068. <para>Figure 8: ACL Instantiation Approach</para>
  4069. </caption>
  4070. </mediaobject>
  4071. </sect2>
  4072. <sect2 id="acls-conclusion">
  4073. <title>Conclusion</title>
  4074. <para>Acegi Security's instance-specific ACL packages shield you from
  4075. much of the complexity of developing your own ACL approach. The
  4076. interfaces and classes detailed above provide a scalable, customisable
  4077. ACL solution that is decoupled from your application code. Whilst the
  4078. reference documentation may suggest complexity, the basic
  4079. implementation is able to support most typical applications
  4080. out-of-the-box.</para>
  4081. </sect2>
  4082. </sect1>
  4083. <sect1 id="security-filters">
  4084. <title>Filters</title>
  4085. <sect2 id="security-filters-overview">
  4086. <title>Overview</title>
  4087. <para>The Acegi Security System for Spring uses filters extensively.
  4088. Each filter is covered in detail in a respective section of this
  4089. document. This section includes information that applies to all
  4090. filters.</para>
  4091. </sect2>
  4092. <sect2 id="security-filters-filtertobeanproxy">
  4093. <title>FilterToBeanProxy</title>
  4094. <para>Most filters are configured using the
  4095. <literal>FilterToBeanProxy</literal>. An example configuration from
  4096. <literal>web.xml</literal> follows:</para>
  4097. <para><programlisting>&lt;filter&gt;
  4098. &lt;filter-name&gt;Acegi HTTP Request Security Filter&lt;/filter-name&gt;
  4099. &lt;filter-class&gt;net.sf.acegisecurity.util.FilterToBeanProxy&lt;/filter-class&gt;
  4100. &lt;init-param&gt;
  4101. &lt;param-name&gt;targetClass&lt;/param-name&gt;
  4102. &lt;param-value&gt;net.sf.acegisecurity.ClassThatImplementsFilter&lt;/param-value&gt;
  4103. &lt;/init-param&gt;
  4104. &lt;/filter&gt;</programlisting></para>
  4105. <para>Notice that the filter in <literal>web.xml</literal> is actually
  4106. a <literal>FilterToBeanProxy</literal>, and not the filter that will
  4107. actually implements the logic of the filter. What
  4108. <literal>FilterToBeanProxy</literal> does is delegate the
  4109. <literal>Filter</literal>'s methods through to a bean which is
  4110. obtained from the Spring application context. This enables the bean to
  4111. benefit from the Spring application context lifecycle support and
  4112. configuration flexibility. The bean must implement
  4113. <literal>javax.servlet.Filter</literal>.</para>
  4114. <para>The <literal>FilterToBeanProxy</literal> only requires a single
  4115. initialization parameter, <literal>targetClass</literal> or
  4116. <literal>targetBean</literal>. The <literal>targetClass</literal>
  4117. parameter locates the first object in the application context of the
  4118. specified class, whilst <literal>targetBean</literal> locates the
  4119. object by bean name. Like standard Spring web applications, the
  4120. <literal>FilterToBeanProxy</literal> accesses the application context
  4121. via<literal>
  4122. WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>,
  4123. so you should configure a <literal>ContextLoaderListener</literal> in
  4124. <literal>web.xml</literal>.</para>
  4125. <para>There is a lifecycle issue to consider when hosting
  4126. <literal>Filter</literal>s in an IoC container instead of a servlet
  4127. container. Specifically, which container should be responsible for
  4128. calling the <literal>Filter</literal>'s "startup" and "shutdown"
  4129. methods? It is noted that the order of initialization and destruction
  4130. of a <literal>Filter</literal> can vary by servlet container, and this
  4131. can cause problems if one <literal>Filter</literal> depends on
  4132. configuration settings established by an earlier initialized
  4133. <literal>Filter</literal>. The Spring IoC container on the other hand
  4134. has more comprehensive lifecycle/IoC interfaces (such as
  4135. <literal>InitializingBean</literal>,
  4136. <literal>DisposableBean</literal>, <literal>BeanNameAware</literal>,
  4137. <literal>ApplicationContextAware</literal> and many others) as well as
  4138. a well-understood interface contract, predictable method invocation
  4139. ordering, autowiring support, and even options to avoid implementing
  4140. Spring interfaces (eg the <literal>destroy-method</literal> attribute
  4141. in Spring XML). For this reason we recommend the use of Spring
  4142. lifecycle services instead of servlet container lifecycle services
  4143. wherever possible. By default <literal>FilterToBeanProxy</literal>
  4144. will not delegate <literal>init(FilterConfig)</literal> and
  4145. <literal>destroy()</literal> methods through to the proxied bean. If
  4146. you do require such invocations to be delegated, set the
  4147. <literal>lifecycle</literal> initialization parameter to
  4148. <literal>servlet-container-managed</literal>.</para>
  4149. </sect2>
  4150. <sect2 id="security-filters-filterchainproxy">
  4151. <title>FilterChainProxy</title>
  4152. <para>Whilst <literal>FilterToBeanProxy</literal> is a very useful
  4153. class, the problem is that the lines of code required for
  4154. <literal>&lt;filter&gt;</literal> and
  4155. <literal>&lt;filter-mapping&gt;</literal> entries in
  4156. <literal>web.xml</literal> explodes when using more than a few
  4157. filters. To overcome this issue, Acegi Security provides a
  4158. <literal>FilterChainProxy</literal> class. It is wired using a
  4159. <literal>FilterToBeanProxy</literal> (just like in the example above),
  4160. but the target class is
  4161. <literal>net.sf.acegisecurity.util.FilterChainProxy</literal>. The
  4162. filter chain is then declared in the application context, using code
  4163. such as this:</para>
  4164. <para><programlisting>&lt;bean id="filterChainProxy" class="net.sf.acegisecurity.util.FilterChainProxy"&gt;
  4165. &lt;property name="filterInvocationDefinitionSource"&gt;
  4166. &lt;value&gt;
  4167. CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
  4168. PATTERN_TYPE_APACHE_ANT
  4169. /webServices/**=httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,securityEnforcementFilter
  4170. /**=httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,securityEnforcementFilter
  4171. &lt;/value&gt;
  4172. &lt;/property&gt;
  4173. &lt;/bean&gt;</programlisting></para>
  4174. <para>You may notice similarities with the way
  4175. <literal>SecurityEnforcementFilter</literal> is declared. Both regular
  4176. expressions and Ant Paths are supported, and the most specific URIs
  4177. appear first. At runtime the <literal>FilterChainProxy</literal> will
  4178. locate the first URI pattern that matches the current web request.
  4179. Each of the corresponding configuration attributes represent the name
  4180. of a bean defined in the application context. The filters will then be
  4181. invoked in the order they are specified, with standard
  4182. <literal>FilterChain</literal> behaviour being respected (a
  4183. <literal>Filter</literal> can elect not to proceed with the chain if
  4184. it wishes to end processing).</para>
  4185. <para>As you can see, <literal>FitlerChainProxy</literal> requires the
  4186. duplication of filter names for different request patterns (in the
  4187. above example, <literal>httpSessionContextIntegrationFilter</literal>
  4188. and <literal>securityEnforcementFilter</literal> are duplicated). This
  4189. design decision was made to enable <literal>FilterChainProxy</literal>
  4190. to specify different <literal>Filter</literal> invocation orders for
  4191. different URI patterns, and also to improve both the expressiveness
  4192. (in terms of regular expressions, Ant Paths, and any custom
  4193. <literal>FilterInvocationDefinitionSource</literal> implementations)
  4194. and clarity of which <literal>Filter</literal>s should be
  4195. invoked.</para>
  4196. <para>You may have noticed we have declared two
  4197. <literal>HttpSessionContextIntegrationFilter</literal>s in the filter
  4198. chain (<literal>ASC</literal> is short for
  4199. <literal>allowSessionCreation</literal>, a property of
  4200. <literal>HttpSessionContextIntegrationFilter</literal>). As web
  4201. services will never present a <literal>jsessionid</literal> on future
  4202. requests, creating <literal>HttpSession</literal>s for such user
  4203. agents would be wasteful. If you had a high-volume application which
  4204. required maximum scalability, we recommend you use the approach shown
  4205. above. For smaller applications, using a single
  4206. <literal>HttpSessionContextIntegrationFilter</literal> (with its
  4207. default <literal>allowSessionCreation</literal> as
  4208. <literal>true</literal>) would likely be sufficient.</para>
  4209. <para>In relation to lifecycle issues, the
  4210. <literal>FilterChainProxy</literal> will always delegate
  4211. <literal>init(FilterConfig)</literal> and <literal>destroy()</literal>
  4212. methods through to the underlaying <literal>Filter</literal>s if such
  4213. methods are called against <literal>FilterChainProxy</literal> itself.
  4214. In this case, <literal>FilterChainProxy</literal> guarantees to only
  4215. initialize and destroy each <literal>Filter</literal> once,
  4216. irrespective of how many times it is declared by the
  4217. <literal>FilterInvocationDefinitionSource</literal>. You control the
  4218. overall choice as to whether these methods are called or not via the
  4219. <literal>lifecycle</literal> initialization parameter of the
  4220. <literal>FilterToBeanProxy</literal> that proxies
  4221. <literal>FilterChainProxy</literal>. As discussed above, by default
  4222. any servlet container lifecycle invocations are not delegated through
  4223. to <literal>FilterChainProxy</literal>.</para>
  4224. </sect2>
  4225. <sect2 id="security-filters-order">
  4226. <title>Filter Ordering</title>
  4227. <para>The order that filters are defined in <literal>web.xml</literal>
  4228. is important. NB: THE FILTER ORDER CHANGED FROM VERSION 0.8.0.</para>
  4229. <para>Irrespective of which filters you are actually using, the order
  4230. of the <literal>&lt;filter-mapping&gt;</literal>s should be as
  4231. follows:</para>
  4232. <orderedlist>
  4233. <listitem>
  4234. <para><literal>ChannelProcessingFilter</literal>, because it might
  4235. need to redirect to a different protocol</para>
  4236. </listitem>
  4237. <listitem>
  4238. <para><literal>HttpSessionContextIntegrationFilter</literal>, so a
  4239. <literal>Context</literal> can be setup in the
  4240. <literal>ContextHolder</literal> at the beginning of a web
  4241. request, and any changes to the Context can be copied to the
  4242. <literal>HttpSession</literal> when the web request ends (ready
  4243. for use with the next web request)</para>
  4244. </listitem>
  4245. <listitem>
  4246. <para>Authentication processing mechanisms -
  4247. <literal>AuthenticationProcessingFilter</literal>,
  4248. <literal>CasProcessingFilter</literal>,
  4249. <literal>BasicProcessingFilter, HttpRequestIntegrationFilter,
  4250. JbossIntegrationFilter</literal> etc - so that the
  4251. <literal>ContextHolder</literal> can be modified to contain a
  4252. valid <literal>Authentication</literal> request token</para>
  4253. </listitem>
  4254. <listitem>
  4255. <para>The <literal>ContextHolderAwareRequestFilter</literal>, if
  4256. you are using it to install an Acegi Security aware
  4257. <literal>HttpServletRequestWrapper</literal> into your servlet
  4258. container</para>
  4259. </listitem>
  4260. <listitem>
  4261. <para><literal>RememberMeProcessingFilter</literal>, so that if no
  4262. earlier authentication processing mechanism updated the
  4263. <literal>ContextHolder</literal>, and the request presents a
  4264. cookie that enables remember-me services to take place, a suitable
  4265. remembered <literal><literal>Authentication</literal></literal>
  4266. object will be put there</para>
  4267. </listitem>
  4268. <listitem>
  4269. <para><literal>AnonymousProcessingFilter</literal>, so that if no
  4270. earlier authentication processing mechanism updated the
  4271. <literal>ContextHolder</literal>, an anonymous
  4272. <literal>Authentication</literal> object will be put there</para>
  4273. </listitem>
  4274. <listitem>
  4275. <para><literal>SecurityEnforcementFilter</literal>, to protect web
  4276. URIs and catch any Acegi Security exceptions so that an
  4277. appropriate <literal>AuthenticationEntryPoint</literal> can be
  4278. launched</para>
  4279. </listitem>
  4280. </orderedlist>
  4281. <para>All of the above filters use
  4282. <literal>FilterToBeanProxy</literal> or
  4283. <literal>FilterChainProxy</literal>, which is discussed in the
  4284. previous sections. It is recommended that a single
  4285. <literal>FilterToBeProxy</literal> proxy through to a single
  4286. <literal>FilterChainProxy</literal> for each application, with that
  4287. <literal>FilterChainProxy</literal> defining all of the Acegi Security
  4288. <literal>Filter</literal>s.</para>
  4289. <para>If you're using SiteMesh, ensure the Acegi Security filters
  4290. execute before the SiteMesh filters are called. This enables the
  4291. <literal>ContextHolder</literal> to be populated in time for use by
  4292. SiteMesh decorators.</para>
  4293. </sect2>
  4294. </sect1>
  4295. <sect1 id="security-sample">
  4296. <title>Contacts Sample Application</title>
  4297. <para>Included with the Acegi Security System for Spring is a very
  4298. simple application that can demonstrate the basic security facilities
  4299. provided by the system (and confirm your Container Adapter is properly
  4300. configured if you're using one).</para>
  4301. <para>If you build from CVS, the Contacts sample application includes
  4302. three deployable versions:
  4303. <literal>acegi-security-sample-contacts-filter.war</literal> is
  4304. configured with the HTTP Session Authentication approach. The
  4305. <literal><literal>acegi-security-sample-contacts-ca.war</literal></literal>
  4306. is configured to use a Container Adapter. Finally,
  4307. <literal>acegi-security-sample-contacts-cas.war</literal> is designed to
  4308. work with a Yale CAS server. If you're just wanting to see how the
  4309. sample application works, please use
  4310. <literal><literal>acegi-security-sample-contacts-filter.war</literal></literal>
  4311. as it does not require special configuration of your container. This is
  4312. also the artifact included in ofiical release ZIPs.</para>
  4313. <para>To deploy, simply copy the relevant WAR file from the Acegi
  4314. Security System for Spring distribution into your container’s
  4315. <literal>webapps</literal> directory.</para>
  4316. <para>After starting your container, check the application can load.
  4317. Visit
  4318. <literal>http://localhost:</literal><literal><literal>8080/</literal>acegi-security-sample-contacts-filter</literal>
  4319. (or whichever URL is appropriate for your web container and the WAR you
  4320. deployed). A random contact should be displayed. Click "Refresh" several
  4321. times and you will see different contacts. The business method that
  4322. provides this random contact is not secured.</para>
  4323. <para>Next, click "Debug". You will be prompted to authenticate, and a
  4324. series of usernames and passwords are suggested on that page. Simply
  4325. authenticate with any of these and view the resulting page. It should
  4326. contain a success message similar to the following:</para>
  4327. <blockquote>
  4328. <para>Context on ContextHolder is of type:
  4329. net.sf.acegisecurity.context.secure.SecureContextImpl</para>
  4330. <para>The Context implements SecureContext.</para>
  4331. <para>Authentication object is of type:
  4332. net.sf.acegisecurity.adapters.PrincipalAcegiUserToken</para>
  4333. <para>Authentication object as a String:
  4334. net.sf.acegisecurity.adapters.PrincipalAcegiUserToken@e9a7c2:
  4335. Username: marissa; Password: [PROTECTED]; Authenticated: true; Granted
  4336. Authorities: ROLE_TELLER, ROLE_SUPERVISOR</para>
  4337. <para>Authentication object holds the following granted
  4338. authorities:</para>
  4339. <para>ROLE_TELLER (getAuthority(): ROLE_TELLER)</para>
  4340. <para>ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)</para>
  4341. <para>SUCCESS! Your [container adapter|web filter] appears to be
  4342. properly configured!</para>
  4343. </blockquote>
  4344. <para>If you receive a different message, and deployed
  4345. <literal>acegi-security-sample-contacts-ca.war</literal>, check you have
  4346. properly configured your Container Adapter as described elsewhere in
  4347. this reference guide.</para>
  4348. <para>Once you successfully receive the above message, return to the
  4349. sample application's home page and click "Manage". You can then try out
  4350. the application. Notice that only the contacts available to the
  4351. currently logged on user are displayed, and only users with
  4352. <literal>ROLE_SUPERVISOR</literal> are granted access to delete their
  4353. contacts. Behind the scenes, the
  4354. <literal>MethodSecurityInterceptor</literal> is securing the business
  4355. objects. If you're using
  4356. <literal><literal>acegi-security-sample-contacts-filter.war</literal></literal>
  4357. or <literal>acegi-security-sample-contacts-cas.war</literal>, the
  4358. <literal>FilterSecurityInterceptor</literal> is also securing the HTTP
  4359. requests. If using either of these WARs, be sure to try visiting
  4360. <literal>http://localhost:8080/contacts/secure/super</literal>, which
  4361. will demonstrate access being denied by the
  4362. <literal>SecurityEnforcementFilter</literal>. Note the sample
  4363. application enables you to modify the access control lists associated
  4364. with different contacts. Be sure to give this a try and understand how
  4365. it works by reviewing the sample application's application context XML
  4366. files.</para>
  4367. <para>The Contacts sample application also include a
  4368. <literal>client</literal> directory. Inside you will find a small
  4369. application that queries the backend business objects using several web
  4370. services protocols. This demonstrates how to use the Acegi Security
  4371. System for Spring for authentication with Spring remoting protocols. To
  4372. try this client, ensure your servlet container is still running the
  4373. Contacts sample application, and then execute <literal>client marissa
  4374. koala</literal>. The command-line parameters respectively represent the
  4375. username to use, and the password to use. Note that you may need to edit
  4376. <literal>client.properties</literal> to use a different target
  4377. URL.</para>
  4378. <para>Please note the sample application's <literal>client</literal>
  4379. does not currently support CAS. You can still give it a try, though, if
  4380. you're ambitious: try <literal>client _cas_stateless_
  4381. YOUR-SERVICE-TICKET-ID</literal>.</para>
  4382. </sect1>
  4383. <sect1 id="security-become-involved">
  4384. <title>Become Involved</title>
  4385. <para>We welcome you to become involved in the Acegi Security System for
  4386. Spring project. There are many ways of contributing, including reading
  4387. the mailing list and responding to questions from other people, writing
  4388. new code, improving existing code, assisting with documentation, or
  4389. simply making suggestions.</para>
  4390. <para>SourceForge provides CVS services for the project, allowing
  4391. anybody to access the latest code. If you wish to contribute new code,
  4392. please observe the following requirements. These exist to maintain the
  4393. quality and consistency of the project:</para>
  4394. <itemizedlist>
  4395. <listitem>
  4396. <para>Use a suitable IDE Jalopy plug-in to convert your code into
  4397. the project's consistent style</para>
  4398. </listitem>
  4399. <listitem>
  4400. <para>Ensure your code does not break any unit tests (run the Maven
  4401. <literal>test:test</literal> goal)</para>
  4402. </listitem>
  4403. <listitem>
  4404. <para>If you have added new code, please provide suitable unit tests
  4405. (use the Maven <literal>clover:html-report</literal> to view
  4406. coverage)</para>
  4407. </listitem>
  4408. <listitem>
  4409. <para>Join the acegisecurity-developer and acegisecurity-cvs mailing
  4410. lists so you're in the loop</para>
  4411. </listitem>
  4412. <listitem>
  4413. <para>Use CamelCase</para>
  4414. </listitem>
  4415. <listitem>
  4416. <para>Add a CVS <literal>$Id: index.xml,v 1.3 2004/04/02 21:12:25
  4417. fbos Exp $</literal> tag to the JavaDocs for any new class you
  4418. create</para>
  4419. </listitem>
  4420. </itemizedlist>
  4421. </sect1>
  4422. <sect1 id="security-further">
  4423. <title>Further Information</title>
  4424. <para>Questions and comments on the Acegi Security System for Spring are
  4425. welcome. Please use the Spring Community Forum web site at
  4426. <literal>http://forum.springframework.org</literal>. You're also welcome
  4427. to join the acegisecurity-developer mailing list. Our project home page
  4428. (where you can obtain the latest release of the project and access to
  4429. CVS, mailing lists, forums etc) is at
  4430. <literal>http://acegisecurity.sourceforge.net</literal>.</para>
  4431. </sect1>
  4432. </chapter>
  4433. </book>