Granting Permissions
====================

You can grant permissions to principals with 
a PermissionManager. For example, if all registered 
users should have permission to view contact details 
and to create new contacts, you could grant them the 
permissions when the user account is created.

.. code-block:: python

     from zope.app.security.interfaces import IAuthentication
     from zope.app.authentication.principalfolder import InternalPrincipal

     # note: the securitypolicy package was moved in Grok 0.12+ from zope.app. to zope.
     from zope.securitypolicy.interfaces import IPrincipalPermissionManager

     def addUser(username, password, realname):
         """Create a new user.

         create a new user and give it the authorizations,
         ``ViewContacts`` and ``EditContacts``. This example assumes
         you are using a Pluggable Authentication Utility (PAU) /
         PrincipalFolder, which you have to create and register when
         creating your Application.
         """

         pau = component.getUtility(IAuthentication)
         principals = pau['principals']
         principals[username] = InternalPrincipal(username, password, realname)

         # grant the user permission to view and create contacts
         # everywhere in the site
         permission_man = IPrincipalPermissionManager(grok.getSite())

         # NOTE that you need a principal ID. If you are
         # authenticating users with a PAU this is normally the user
         # name prepended with the principals-folder prefix (and the
         # PAU-prefix as well, if set)
         permission_man.grantPermissionToPrincipal (
            'mysite.ViewContacts',
            principals.prefix + username)
         permission_man.grantPermissionToPrincipal(
            'mysite.AddContacts',
            principals.prefix + username)

Permissions are granted for the context for which the PermissionManager is
created, and -- if not explicitly overridden -- all its children. The above
example grants ``View`` and ``Add`` permissions for the complete site, unless
a folder down in the hierarchy revokes the permission.

If you want users to be able to edit only their own ``ContactInfos``, you have
to give them the ``Edit`` permission only within the context of the
``ContactInfo``-object itself

.. code-block:: python

     class AddContact(grok.AddForm):
         """Add a contact.
         """

         # Only users with permission 'mysite.AddContacts' can use
         # this.
         #
         # NOTE that if you don't protect this Form, anyone -- even
         # anonymous/unauthenticated users -- could add ``Contacts``
         # to the site.
         grok.require('mysite.AddContacts')

         #automagically generate form fields
         form_fields = grok.AutoFields(IContactInfo)

         @grok.action('Create')
         def create(self, **kw):
             # Create and add the ``ContactInfo`` to our context
             # (normally a folder/container)
             contact = ContactInfo()
             self.applyData(contact, **kw)
             self.context[contact.first_name] = contact

             # Grant the current user the Edit permission, but only in
	     # the context of the newly created object.
             permission_man = IPrincipalPermissionManager(contact)
             permission_man.grantPermissionToPrincipal(
                 'mysite.EditContacts',
                 self.request.principal.id)
             self.redirect(self.url(contact))

     class EditContact(grok.EditForm):
         """Edit a contact.
         """

         #only users with permission 'mysite.EditContacts' can use this
         grok.require('mysite.EditContacts')

         form_fields = grok.AutoFields(IContactInfo)

         @grok.action('Save Changes')
         def edit(self, **data):
             self.applyData(self.context, **data)
             self.redirect(self.url(self.context))