Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Changes between Version 33 and Version 34 of IdentityManagement


Ignore:
Timestamp:
04/04/06 12:10:23 (13 years ago)
Author:
fredlin
Comment:

refactor

Legend:

Unmodified
Added
Removed
Modified
  • IdentityManagement

    v33 v34  
    55It's a short How To for getting TurboGears identity management support up and running. 
    66 
     7Identity Management can be used in either controller or templates. 
     8 
    79This How To is written from the perspective of a fresh quick-started project, but most everything applies for existing projects. 
    810 
    9 == Quick start example == 
     11== Use Identity in Controller == 
    1012 
    1113=== Step 1 - Create new project ===  
     
    1416$ tg-admin quickstart  
    1517}}} 
    16 Name your project idtest and set the dburi in dev.cfg to point to a server and database you want to use. 
     18Name your project as your "project_name" and set the database uri in "project_name/dev.cfg" to point to a server and database you want to use. refer [http://www.turbogears.org/docs/wiki20/ here] 
    1719 
    1820=== Step 2 - Edit project_name/config/app.cfg === 
    19 Edit app.cfg. Under the "IDENTITY" heading (around line 68), uncomment and edit the following to turn on identity management. Edit the failure url as well. 
    20  
    21 {{{ 
    22 #!python 
     21Edit app.cfg. uncomment and edit the following to turn on identity management. Edit the failure url as well. 
     22 
     23{{{ 
     24#!python 
     25# visit.on=False 
    2326visit.on=True 
     27 
     28# identity.on=False 
    2429identity.on = True 
     30 
     31# identity.failure_url=None 
    2532identity.failure_url = "/login" 
     33 
    2634}}} 
    2735 
     
    3846 
    3947=== Step 4 - protect your pages === 
    40 Edit controllers.py,  
    41  
    42 Add this code to the top of the file: 
     48You can protect your pages by using identity decorator(decorator usage is as the expose decorator "@turbogears.expose()" you've learned) 
     49 
     50'''1'''. Edit controllers.py 
     51 
     52Add this code on the top of the file: 
    4353 
    4454{{{ 
     
    4757}}} 
    4858 
    49 If you want protect any page(a python method), add an identity decorator over the page. 
     59'''2'''. Protect Pages 
     60 
     61If you want to protect any method(page is just a python method), add an identity decorator over the method. 
    5062 
    5163The following example use "@identity.require()" to protect the index page: 
     
    5365{{{ 
    5466#!python 
    55     @turbogears.expose(template="omgears.templates.welcome") 
     67    @turbogears.expose(template=".templates.welcome") 
    5668    @identity.require( identity.in_group( "admin" )) 
    5769    def index(self): 
     
    5971}}} 
    6072 
    61 The require decorator checked whether the visitor was a member of the   
    62 admin group AND had the permission foo AND had the permission bar. 
     73The decorator checked whether the visitor was a member of the   
     74admin group. 
    6375 
    6476Let's visit the http://localhost:8080/, now the index page is protected. 
    6577 
    66 Note: You may need to revise the above code for the @identity.require decorator. In a [http://groups.google.com/group/turbogears/browse_thread/thread/8dc90943e2cce3ce/42de9e3ae86f7aaf?q=identity&rnum=1#42de9e3ae86f7aaf mailing list], Jeff Watkins writes the most of usages.(see the end of the post)  
     78There are many @identity.require decorator parameters for you to fit your identity requirements.  
     79 
     80See the API section below.  
    6781 
    6882=== Step 5 - Create a user and group === 
    6983 
    70 We just learn howto protect our page, but now we can't access those pages any more. We need add some user/group/admission to login to the protected pages. 
    71  
    72 Using Catwalk is probably the easiest way to create user/group/permissions(But it doen't work in 0.92a) Use this method if you can't get Catwalk set up. 
    73  
    74 (The following section won't work under 0.9a2. patch is [http://groups.google.com/group/turbogears/browse_thread/thread/e1cd7e5e8cb26bba/9f8ae06fbe07bd5a here]) 
    75  
    76 {{{ 
     84We just learn howto protect our page, but for now we can't access those protected pages any more.  
     85 
     86Since we haven't specify any user or groups for permissions, we need to add some user/group/admission to login to the protected pages. 
     87 
     88{{{ 
     89#!python 
    7790$ tg-admin shell 
    7891 
    79 Python 2.4.1 (#2, Mar 31 2005, 00:05:10)  
    80 [GCC 3.3 20030304 (Apple Computer, Inc. build 1666)] on darwin 
    81 Type "help", "copyright", "credits" or "license" for more information. 
    82 (InteractiveConsole) 
    8392>>> from turbogears.identity.soprovider import * 
    8493>>> hub.begin() 
     
    93102=== Step 6 - Add the user to admin group === 
    94103{{{ 
     104#!python 
    95105$ tg-admin shell 
    96106 
    97 Python 2.4.1 (#2, Mar 31 2005, 00:05:10)  
    98 [GCC 3.3 20030304 (Apple Computer, Inc. build 1666)] on darwin 
    99 Type "help", "copyright", "credits" or "license" for more information. 
    100 (InteractiveConsole) 
    101107>>> from turbogears.identity.model.somodel import * 
    102108>>> hub.begin() 
     
    114120---- 
    115121 
     122== Use Identity in templates == 
     123Identity checks can also be used in kid templates to control the present of stricted areas or links(within any html element). 
     124 
     125'''1'''. Import turbogears.identity 
     126 
     127Make sure you import turbogears.identity in your template (anywhere before you call the turbogears.identity) 
     128 
     129{{{ 
     130<?python from turbogears import identity ?> 
     131}}} 
     132 
     133'''2'''. Control the stricted areas 
     134 
     135We Control the stricted areas by using "py:if" statements: 
     136 
     137=== Restrict access groups === 
     138{{{ 
     139<a py:if="'admin' in identity.current.groups" href="/test">This is a link for admin</a> 
     140}}} 
     141 
     142=== Restrict access permissions === 
     143{{{ 
     144<div py:if="'write' in identity.current.permissions">This is a write permissions area</div> 
     145}}} 
     146 
     147---- 
     148 
    116149== API == 
    117150 
     
    120153You need to use the permission control functions in the {{{identity}}} namespace. For example: 
    121154 
     155==== Restrict access groups ==== 
    122156{{{ 
    123157#!python 
     
    132166 
    133167@identity.require( identity.in_any_group( "admin", "editor" ) ) 
    134  
     168}}} 
     169 
     170==== Restrict access permissions ==== 
     171 
     172{{{ 
     173#!python 
    135174@identity.require( identity.has_permission( "edit" ) ) 
    136175 
     
    154193{{{ 
    155194#!python 
    156      @identity.require( All( identity.from_host( "127.0.0.1" ), identity.has_permission 
    157 ( "edit" ) ) ) 
    158      @identity.require( All( identity.from_any_host( "127.0.0.1", "10.0.0.1" ),identity.in_group( "editor" ) ) ) 
    159 }}} 
    160  
    161  
    162 You can also use these same predicates in your own code: 
    163 {{{ 
    164 #!python 
    165      if identity.in_group( "admin" ) and identity.has_permission( "edit" ): 
    166          pass 
    167      else: 
    168          pass 
    169  
    170 }}} 
     195     @identity.require( All( identity.from_host( "127.0.0.1" ), identity.has_permission( "edit" ) ) ) 
     196 
     197     @identity.require( All( identity.from_any_host( "127.0.0.1", "10.0.0.1", identity.in_group("editor" ) ) ) 
     198}}} 
     199 
    171200 
    172201---- 
     
    180209There are three ways to Strict the group Access: 
    181210 
    182 '''1''' Protect your sub-directory  
     211'''1'''. Protect your sub-directory  
    183212 
    184213To turn on identity login for an entire controller(restrict access to whole subdirectory), you should be able to derive your Controller from identity.SecureResource and define a require attribute at the class level. 
     
    194223You can apply whatever decorators you want on the methods of the Toxicologia instance. So each method could have additional restrictions. And Toxicologia could have SecureObjects as well. However, access to exposed methods of Toxicologia and any SecureObjects would have to satisfy the authorisation requirements for Toxicologia. 
    195224 
    196 '''2''' Check the permissions explicitly 
     225'''2'''. Check the permissions explicitly 
    197226 
    198227Derive your Controller from identity.SecureResource and define a require attribute at the method level 
     
    208237             raise identity.GroupMembershipRequiredException( ("admin", "super") ) 
    209238}}} 
     239 
    210240This will work because SecureResource wraps all exposed methods with code that checks permissions and traps IdentityExceptions. So if your code throws, er, raises an IdentityException, everything will be handled correctly. 
    211241 
    212242Of course, you can then pull your authorisation logic out into a function that you call rather than copying and pasting into each function that requires it. 
    213243 
    214 '''3''' Write your own decorator function  
     244You can also use these similar predicates in your own code: 
     245{{{ 
     246#!python 
     247     if identity.in_group( "admin" ) and identity.has_permission( "edit" ): 
     248         pass 
     249     else: 
     250         pass 
     251 
     252}}} 
     253 
     254'''3'''. Write your own decorator function  
    215255 
    216256This is not for the faint at heart. But it gives you absolute flexibility.  
     
    220260---- 
    221261 
    222  
    223 === Identity and Kid templates === 
    224 In addition to restricting access to methods in controller files, identity checks can also be used to limit what links(or any other element, for that matter) show up in kid templates. This is done using py:if="" statements, like so: 
    225 {{{ 
    226 <a py:if="'admin' in turbogears.identity.current.groups" href="/test">This is a test</a> 
    227 <a py:if="'write' in turbogears.identity.current.permissions" href="/test">This is a test</a> 
    228 }}} 
    229 Make sure you import turbogears somewhere in your template for those identity checks to work.   
    230 {{{ 
    231 <?python import turbogears ?> 
    232 }}} 
    233 or, to save on typing,  
    234 {{{ 
    235 <?python from turbogears import identity ?> 
    236 }}} 
    237 and omit the "turbogears" part of the py:if statement. 
    238 ---- 
    239262 
    240263 
     
    243266You can use your own class on Identity Management. 
    244267 
    245 '''1''' Create SQL tables   
     268'''1'''. Create SQL tables   
    246269 
    247270Run the application as Step 3. All TG_* tables will be created 
    248271 
    249 '''2''' Edit project_name/config/app.cfg,  
     272'''2'''. Edit project_name/config/app.cfg,  
    250273 
    251274Edit app.cfg, remove the comments from "identity.soprovider" lines.  
     
    264287Change model."User", "Group", "Permission" to whatever you prefer.  
    265288 
    266 '''3''' Run the application  
     289'''3'''. Run the application  
    267290 
    268291Run the application again as in Step 3. Then you can use your classes to manipulate TurboGear Identity Management. 
     
    271294 
    272295---- 
    273  
    274 = Following contents haven't been re-processed yet = 
    275  
    276  
    277 === Applying security settings, not from source code, but from configuration data === 
    278  
    279 You should be able to specify security settings not only from source code but via some other means. The goal is to allow an administrator to set the security policy, not the programmer. 
    280  
    281 ---- 
    282  
    283  
    284 == FAQ's == 
    285  
    286 === How do I retrieve the userId in my application code? === 
    287  
    288 Actually you can access the entire User object by accessing turbogears.identity.current.user. This gives you access to the userId, displayName, emailAddress, and creation date. 
    289  
    290 === So, if I wanted to access the users’ group info, how would I do that? === 
    291  
    292 There are two ways you can access the group information. 
    293  
    294 '''1.''' Via the current identity object: 
     296== Retrieve logged users' identity infomation == 
     297 
     298=== Retrieve user identity infomation === 
     299 
     300We can access the entire User object by accessing "turbogears.identity.current.user" to get user identity infomation. This gives you access to the userId, displayName, emailAddress, and creation date. 
     301 
     302=== Retrieve users’ group identity infomation === 
     303 
     304There are two ways to access the group information. 
     305 
     306'''1'''. Via the current identity object: 
    295307{{{ 
    296308#!python 
     
    299311    pass 
    300312}}} 
    301 '''2.''' Via the user object on the current identity: 
     313 
     314'''2'''. Via the user object on the current identity: 
    302315{{{ 
    303316#!python 
     
    311324 
    312325 
     326Using Catwalk is probably the easiest way to create user/group/permissions(But it doen't work in 0.92) Use this method if you can't get Catwalk set up. 
     327 
     328Using tg-admin shell  to add identity user/group is not work under 0.9a2. patch is [http://groups.google.com/group/turbogears/browse_thread/thread/e1cd7e5e8cb26bba/9f8ae06fbe07bd5a here] 
     329 
    313330  '''TurboGears identity management architecture was originally from [http://metrocat.org/nerd/2005/10/identity-management-for-turbogears Jeff Watkins' blog].''' 
     331 
     332 
     333=== Applying security settings, not from source code, but from configuration data === 
     334(Not implement yet) 
     335 
     336You should be able to specify security settings not only from source code but via some other means. The goal is to allow an administrator to set the security policy, not the programmer. 
     337----