Skip to content

Commit

Permalink
- added doctests to long_description, so they'll show up on pypi home…
Browse files Browse the repository at this point in the history 
…page

- made text a bit nicer to read
  • Loading branch information
Michael Howitz committed Jan 3, 2009
1 parent 7446fda commit 524aefb
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 63 deletions.
6 changes: 6 additions & 0 deletions setup.py
View file
Expand Up @@ -29,6 +29,12 @@ def read(*rnames):
description = "IAuthentication implementation for for Zope3",
long_description=(
read('README.txt')
+ '\n\n.. contents::\n\n' +
read('src', 'z3c', 'authenticator', 'README.txt')
+ '\n\n' +
read('src', 'z3c', 'authenticator', 'group.txt')
+ '\n\n' +
read('src', 'z3c', 'authenticator', 'vocabulary.txt')
+ '\n\n' +
read('CHANGES.txt')
),
Expand Down
134 changes: 71 additions & 63 deletions src/z3c/authenticator/README.txt
View file
Expand Up @@ -2,8 +2,8 @@
IAuthentication Utility
=======================

The Authenticator package provides a framework for authenticating principals
and associating information with them. It uses plugins and subscribers to get
The Authenticator package provides a framework for authenticating principals
and associating information with them. It uses plugins and subscribers to get
its work done.

For a simple authentication utility to be used, it should be registered as a
Expand All @@ -17,7 +17,7 @@ zope.app.authentication implementation.
Security
--------

The Authenticator supports unique id tokens for principals. This means
The Authenticator supports unique id tokens for principals. This means
principal that get deleted and again added with the same id, login etc. do
not have the same id again. We support this by generate a user id token
generated by the host id, timestamp, a random string and the login attribute.
Expand All @@ -26,32 +26,32 @@ generated by the host id, timestamp, a random string and the login attribute.
What's different then in PluggableAuthentication
------------------------------------------------

We use a different pattern for IAuthenticatorPlugins in this implementation
then used in PluggableAuthentication located in zope.app.authentication.
Because the pluggable authentication is not very handy when it comes to
implement custom principal information. The IPrincipalInfo hook supporting
not propagate the password of a IInternalPrincipal is droped in this
We use a different pattern for IAuthenticatorPlugins in this implementation
then used in PluggableAuthentication located in zope.app.authentication.
Because the pluggable authentication is not very handy when it comes to
implement custom principal information. The IPrincipalInfo hook supporting
not propagate the password of a IInternalPrincipal is droped in this
implementation.

In our implementation we offer a IFoundPrincipal and IAuthenticatedPrincipal
which are implemented as adapters for a IUser. This adapters do not offer
it's context which is the real IUser.

The Authenticator doesn't use a prefix. The usage of a prefix is only
implemented in the IGroupContainer.
implemented in the IGroupContainer.

We do not use a prefix in the IUserContainer because of the used unique user
id tokens. This will make sure that the same principal id doesn't get used at
a later time (common criteria). There is a ``add`` method which creates
this id for you based on the login. The __setitem__ should not get used
We do not use a prefix in the IUserContainer because of the used unique user
id tokens. This will make sure that the same principal id doesn't get used at
a later time (common criteria). There is a ``add`` method which creates
this id for you based on the login. The __setitem__ should not get used
directly for adding IUser instances anymore. We heavily restricted the
usage of this method. See the inline doc tests in __setitem__ for more info.


Authentication
==============

The primary job of Authenticator is to authenticate principals. It uses
The primary job of Authenticator is to authenticate principals. It uses
two types of plug-ins in its work:

- Credentials Plugins
Expand All @@ -68,47 +68,55 @@ Authenticator plugins are responsible for authenticating the credentials
extracted by a credentials plugin. They are also typically able to create
principal objects for credentials they successfully authenticate.

Given a request object, the Authenticator returns a principal object, if it
can. The Authenticator utility does this by first iterateing through its
credentials plugins to obtain a set of credentials. If it gets credentials, it
Given a request object, the Authenticator returns a principal object, if it
can. The Authenticator utility does this by first iterateing through its
credentials plugins to obtain a set of credentials. If it gets credentials, it
iterates through its authenticator plugins to authenticate them.

If an authenticator succeeds in authenticating a set of credentials, the
Authenticator uses the authenticator to create a principal
corresponding to the credentials. The authenticator notifies subscribers if
an authenticated principal is created. Subscribers are responsible for adding
data, especially groups, to the principal. Typically, if a subscriber adds
If an authenticator succeeds in authenticating a set of credentials, the
Authenticator uses the authenticator to create a principal
corresponding to the credentials. The authenticator notifies subscribers if
an authenticated principal is created. Subscribers are responsible for adding
data, especially groups, to the principal. Typically, if a subscriber adds
data, it should also add corresponding interface declarations.


FAQ
---

Here some usefull hints.
Here some useful hints:

How should I set permission for principals -- You can apply a roles to groups
and apply permissions to roles. Or you can directly apply local permisssions
to groups or to principals. After setup this mappings you can grant roles to
groups. I always recommend a principal - group and permission - role mapping,
then this gives you the most possible abstraction which is usefullif it comes
to manage permission and principals without to invoke directly principals and
How should I set permission for principals?

You can apply a roles to groups
and apply permissions to roles. Or you can directly apply local permisssions
to groups or to principals. After setup this mappings you can grant roles to
groups. I always recommend a principal - group and permission - role mapping,
then this gives you the most possible abstraction which is useful if it comes
to manage permission and principals without to invoke directly principals and
permissions itself. but of corse you can grant permissions to groups or the
worst thing directly to principals. Grant permission to principals is only
useful if it comes to selective local permission settings for selected
worst thing directly to principals. Grant permission to principals is only
useful if it comes to selective local permission settings for selected
principals e.g. a ownership like permission setup.

How can I set permission for all principals -- You can register one
How can I set permission for all principals?

You can register one
group as IEveryone utility. This IGroup utility get applied to all principals.

Can I apply local groups to unauthenticated principals -- Yes this will work.
Can I apply local groups to unauthenticated principals?

Yes this will work.
Since the last refactoring I refactored the IGroup implementation which makes
it compatible with the principalregistry API. This means you can now register
one local group as a unnamed IUnauthenticatedGroup. You can also register one
local group as an unnamed IAuthenticatedGroup utility which will get applied
to every authenticated principal or a unnamed utility for
one local group as a unnamed IUnauthenticatedGroup. You can also register one
local group as an unnamed IAuthenticatedGroup utility which will get applied
to every authenticated principal or a unnamed utility for
IUnauthenticatedGroup.

Can I apply a local group to every principal -- Yes, this is possible if
Can I apply a local group to every principal?

Yes, this is possible if
register a local unnamed utility providing IEveryoneGroup.


Expand Down Expand Up @@ -148,23 +156,23 @@ First setup a UserContainer which will store the principals:

>>> from z3c.authenticator.user import UserContainer
>>> authPlugin = UserContainer()

Now we have a UserContainer that provides a IUserContainer:

>>> interfaces.IUserContainer.providedBy(authPlugin)
True

Now we will add the created principal to the principal container using the
Now we will add the created principal to the principal container using the
containers method ``add``:

>>> uid, user = authPlugin.add(p)

The method returns the user id and the user object. The id get generated
by the host IP address, the time, a random string and the user login attr.
This token should be unique and guranted that it never get generated twice.
This allows us to add, delete and add the same user again without that such a
This allows us to add, delete and add the same user again without that such a
user will inherit existing permissions. We can test this token by compare it
only with the __name__ of the object in this test since the token will
only with the __name__ of the object in this test since the token will
different every testrun.

>>> user.__name__ == uid
Expand All @@ -190,15 +198,15 @@ The returned user still is our previous added IUser
let's register the UserContainer as a named IAuthenticatorPlugin utility:

>>> import zope.component
>>> zope.component.provideUtility(authPlugin,
... provides=interfaces.IAuthenticatorPlugin,
>>> zope.component.provideUtility(authPlugin,
... provides=interfaces.IAuthenticatorPlugin,
... name='My Authenticator Plugin')


Credentials Plugin
------------------

After setup the user and user container, we'll create a simple credentials
After setup the user and user container, we'll create a simple credentials
plugin:

>>> import zope.interface
Expand All @@ -209,7 +217,7 @@ plugin:
... zope.interface.implements(interfaces.ICredentialsPlugin)
...
... def extractCredentials(self, request):
... return {'login':request.get('login', ''),
... return {'login':request.get('login', ''),
... 'password':request.get('password', '')}
...
... def challenge(self, request):
Expand All @@ -223,22 +231,22 @@ it could be stored in the Authenticator attribute credentialsPlugins.
Use the first and register the plugina utility:

>>> myCredentialsPlugin = MyCredentialsPlugin()
>>> zope.component.provideUtility(myCredentialsPlugin,
>>> zope.component.provideUtility(myCredentialsPlugin,
... name='My Credentials Plugin')


AuthenticatedPrincipal and FoundPrincipal
-----------------------------------------

While authenticator plugins provide user, they are not responsible for
While authenticator plugins provide user, they are not responsible for
creating principals. This function is performed by the Authenticator:

>>> from z3c.authenticator.principal import AuthenticatedPrincipal
>>> from z3c.authenticator.principal import FoundPrincipal
>>> zope.component.provideAdapter(AuthenticatedPrincipal,
>>> zope.component.provideAdapter(AuthenticatedPrincipal,
... provides=interfaces.IAuthenticatedPrincipal)

>>> zope.component.provideAdapter(FoundPrincipal,
>>> zope.component.provideAdapter(FoundPrincipal,
... provides=interfaces.IFoundPrincipal)


Expand Down Expand Up @@ -288,7 +296,7 @@ we get an authenticated principal.
Change login
------------

Change the login of a principal is a allwas a critical task because such a
Change the login of a principal is a allwas a critical task because such a
login together with a password is the key to our implemenation. Let's try to
change the login and check if everything is correct. We can do this by get the
principal from the UserContainer and change the login on the IUser
Expand All @@ -313,7 +321,7 @@ But not with the old one:
>>> auth.authenticate(request) == None
True

The user bob has still the same id as bob2 since the user id token doesn't
The user bob has still the same id as bob2 since the user id token doesn't
get changed be changing the login:

>>> bob.id == bob2.id
Expand Down Expand Up @@ -357,14 +365,14 @@ The principal has the id, title, and description.
>>> event.principal.description
u''

We provide subscribers to these events that can be used for doing custom
We provide subscribers to these events that can be used for doing custom
processing. Note, the principal attibute provides a IAuthenticatedPrincipal:

>>> def addInfo(event):
... id = event.principal.id
... event.principal.description = 'Description for: %s' % id

>>> zope.component.provideHandler(addInfo,
>>> zope.component.provideHandler(addInfo,
... [interfaces.IAuthenticatedPrincipalCreated])

Now, if we authenticate a principal, its description is set:
Expand All @@ -377,13 +385,13 @@ Now, if we authenticate a principal, its description is set:
Customization
-------------

Let's show you how the existing pattern can get used in a real use case. In
Let's show you how the existing pattern can get used in a real use case. In
the next sample we like to provide a additional email attribute for principals.
First we have to define the interfaces declaring the email attribute:

>>> class IMyEmail(zope.interface.Interface):
... email = zope.schema.TextLine(
... title=u'EMail',
... title=u'EMail',
... description=u'The EMail')

>>> class IMyUser(IMyEmail, interfaces.IUser):
Expand All @@ -392,17 +400,17 @@ First we have to define the interfaces declaring the email attribute:
>>> class IMyFoundPrincipal(IMyEmail, interfaces.IFoundPrincipal):
... """Custom IIMyFoundrincipal interface."""

>>> class IMyAuthenticatedPrincipal(IMyEmail,
>>> class IMyAuthenticatedPrincipal(IMyEmail,
... interfaces.IAuthenticatedPrincipal):
... """Custom IAuthenticatedPrincipal interface."""

After the schema, we define a custom principal implementation implementing
After the schema, we define a custom principal implementation implementing
this interface:

>>> class MyUser(User):
... zope.interface.implements(IMyUser)
... def __init__(self, login, password, title, description, email):
... super(MyUser, self).__init__(login, password, title,
... super(MyUser, self).__init__(login, password, title,
... description)
... self.email = email

Expand All @@ -423,16 +431,16 @@ And we have to define the FoundPrincipal for MyUser:
... self.email = principal.email

Note that you can provide different attributes for the found and authenticated
principal if needed. That's up to you what you like to do with this attributes
principal if needed. That's up to you what you like to do with this attributes
later.

Now we need to register our custom authenticated and found principal as
Now we need to register our custom authenticated and found principal as
adapters:

>>> zope.component.provideAdapter(MyAuthenticatedPrincipal,
>>> zope.component.provideAdapter(MyAuthenticatedPrincipal,
... provides=interfaces.IAuthenticatedPrincipal)

>>> zope.component.provideAdapter(MyFoundPrincipal,
>>> zope.component.provideAdapter(MyFoundPrincipal,
... provides=interfaces.IFoundPrincipal)

Now we can use them without any other event subscriber or other registration
Expand Down

0 comments on commit 524aefb

Please sign in to comment.