[Checkins] SVN: z3c.authenticator/trunk/src/z3c/authenticator/README.txt Minor language corrections.
Marius Gedminas
marius at pov.lt
Mon Sep 6 09:04:40 EDT 2010
Log message for revision 116208:
Minor language corrections.
Changed:
U z3c.authenticator/trunk/src/z3c/authenticator/README.txt
-=-
Modified: z3c.authenticator/trunk/src/z3c/authenticator/README.txt
===================================================================
--- z3c.authenticator/trunk/src/z3c/authenticator/README.txt 2010-09-06 06:23:50 UTC (rev 116207)
+++ z3c.authenticator/trunk/src/z3c/authenticator/README.txt 2010-09-06 13:04:40 UTC (rev 116208)
@@ -23,19 +23,19 @@
generated by the host id, timestamp, a random string and the login attribute.
-What's different then in PluggableAuthentication
-------------------------------------------------
+What's different from 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
+than used in PluggableAuthentication from zope.app.authentication,
+because the pluggable authentication is not very handy when it comes to
+implementing 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.
+which are implemented as adapters for a IUser. These adapters do not offer
+their context which is the real IUser.
The Authenticator doesn't use a prefix. The usage of a prefix is only
implemented in the IGroupContainer.
@@ -69,7 +69,7 @@
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
+can. The Authenticator utility does this by first iterating through its
credentials plugins to obtain a set of credentials. If it gets credentials, it
iterates through its authenticator plugins to authenticate them.
@@ -90,16 +90,16 @@
You can apply 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
+ to groups or to principals. After setting up these 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
+ this gives you the most possible abstraction which is useful if it comes
+ to managing permissions and principals without directly invoking principals and
+ permissions themselves. But of course you can grant permissions to groups or the
+ worst thing, directly to principals. Granting permissions to principals is only
useful if it comes to selective local permission settings for selected
- principals e.g. a ownership like permission setup.
+ principals, e.g. an ownership-like permission setup.
-How can I set permission for all principals?
+How can I set permissions for all principals?
You can register one
group as IEveryone utility. This IGroup utility get applied to all principals.
@@ -109,14 +109,14 @@
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
+ one local group as an 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
+ to every authenticated principal or an unnamed utility for
IUnauthenticatedGroup.
Can I apply a local group to every principal?
- Yes, this is possible if
+ Yes, this is possible if you
register a local unnamed utility providing IEveryoneGroup.
@@ -152,33 +152,33 @@
Authenticator Plugin
--------------------
-First setup a UserContainer which will store the principals:
+First set up a UserContainer which will store the principals:
>>> from z3c.authenticator.user import UserContainer
>>> authPlugin = UserContainer()
-Now we have a UserContainer that provides a IUserContainer:
+Now we have a UserContainer that provides an IUserContainer:
>>> interfaces.IUserContainer.providedBy(authPlugin)
True
Now we will add the created principal to the principal container using the
-containers method ``add``:
+container's ``add`` method:
>>> 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
-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
-different every testrun.
+The method returns the user id and the user object. The id gets generated
+from the host IP address, the time, a random string and the user login attr.
+This token should be unique and guaranteed that it will never get generated twice.
+This allows us to add, delete and add the same user again without having such a
+user inheriting existing permissions. We can test this token by comparing it
+only with the __name__ of the object in this test since the token will be
+different every test run.
>>> user.__name__ == uid
True
-The returned user still is our previous added IUser
+The returned user is still our previous added IUser
>>> user is p
True
@@ -195,7 +195,7 @@
>>> user.title
u'Bob'
-let's register the UserContainer as a named IAuthenticatorPlugin utility:
+Let's register the UserContainer as a named IAuthenticatorPlugin utility:
>>> import zope.component
>>> zope.component.provideUtility(authPlugin,
@@ -206,7 +206,7 @@
Credentials Plugin
------------------
-After setup the user and user container, we'll create a simple credentials
+After seting up the user and user container, we'll create a simple credentials
plugin:
>>> import zope.interface
@@ -217,8 +217,8 @@
... zope.interface.implements(interfaces.ICredentialsPlugin)
...
... def extractCredentials(self, request):
- ... return {'login':request.get('login', ''),
- ... 'password':request.get('password', '')}
+ ... return {'login': request.get('login', ''),
+ ... 'password': request.get('password', '')}
...
... def challenge(self, request):
... pass # challenge is a no-op for this plugin
@@ -238,7 +238,7 @@
AuthenticatedPrincipal and FoundPrincipal
-----------------------------------------
-While authenticator plugins provide user, they are not responsible for
+While authenticator plugins provide users, they are not responsible for
creating principals. This function is performed by the Authenticator:
>>> from z3c.authenticator.principal import AuthenticatedPrincipal
@@ -250,8 +250,8 @@
... provides=interfaces.IFoundPrincipal)
-Configuring Authenticator
--------------------------
+Configuring the Authenticator
+-----------------------------
Finally, we'll create the Authenticator itself:
@@ -276,13 +276,13 @@
In this case, we cannot authenticate an empty request. In the same way, we
will not be able to authenticate a request with the wrong credentials:
- >>> request = TestRequest(form={'login':'let me in!', 'password':'secret'})
+ >>> request = TestRequest(form={'login': 'let me in!', 'password': 'secret'})
>>> print auth.authenticate(request)
None
However, if we provide the proper credentials:
- >>> request = TestRequest(form={'login':'bob', 'password':'secret'})
+ >>> request = TestRequest(form={'login': 'bob', 'password': 'secret'})
>>> bob = auth.authenticate(request)
>>> bob
<AuthenticatedPrincipal...>
@@ -293,13 +293,13 @@
we get an authenticated principal.
-Change login
-------------
+Changing login names
+--------------------
-Change the login of a principal is a allwas a critical task because such a
+Changing the login (i.e. username) of a principal is always 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
+change the login and check if everything is correct. We can do this by getting the
+principal from the UserContainer and changing the login on the IUser
implementation:
>>> internal = authPlugin[bob.id]
@@ -307,7 +307,7 @@
Now we should be able to login with the new login:
- >>> request = TestRequest(form={'login':'bob2', 'password':'secret'})
+ >>> request = TestRequest(form={'login': 'bob2', 'password': 'secret'})
>>> bob2 = auth.authenticate(request)
>>> bob2
<AuthenticatedPrincipal ...>
@@ -317,12 +317,12 @@
But not with the old one:
- >>> request = TestRequest(form={'login':'bob', 'password':'secret'})
+ >>> request = TestRequest(form={'login': 'bob', 'password': 'secret'})
>>> auth.authenticate(request) == None
True
The user bob has still the same id as bob2 since the user id token doesn't
-get changed be changing the login:
+get changed by changing the login:
>>> bob.id == bob2.id
True
@@ -331,7 +331,7 @@
Events
------
-Authenticate principal will create events.
+Authenticating a principal will create events.
>>> from zope.component.eventtesting import getEvents
>>> from zope.component.eventtesting import clearEvents
@@ -339,7 +339,7 @@
We can verify that the appropriate event was published:
>>> clearEvents()
- >>> request = TestRequest(form={'login':'bob2', 'password':'secret'})
+ >>> request = TestRequest(form={'login': 'bob2', 'password': 'secret'})
>>> bobAgain = auth.authenticate(request)
And the principal attribute in the event provides the authenticated principal:
@@ -366,7 +366,7 @@
u''
We provide subscribers to these events that can be used for doing custom
-processing. Note, the principal attibute provides a IAuthenticatedPrincipal:
+processing. Note, the principal attibute provides an IAuthenticatedPrincipal:
>>> def addInfo(event):
... id = event.principal.id
@@ -386,7 +386,7 @@
-------------
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.
+the next sample we'd like to provide an additional email attribute for principals.
First we have to define the interfaces declaring the email attribute:
>>> class IMyEmail(zope.interface.Interface):
@@ -431,10 +431,10 @@
... 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
+principals if needed. That's up to you what you like to do with these 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
adapters:
>>> zope.component.provideAdapter(MyAuthenticatedPrincipal,
@@ -443,7 +443,7 @@
>>> zope.component.provideAdapter(MyFoundPrincipal,
... provides=interfaces.IFoundPrincipal)
-Now we can use them without any other event subscriber or other registration
+Now we can use them without any other event subscribers or other registration
in our principal container. Let's add a principal to this container:
>>> p = MyUser(u'max', u'password', u'Max', u'', u'max at foobar.com')
@@ -465,7 +465,7 @@
Let's try to authenticate...
- >>> request = TestRequest(form={'login':'max', 'password':'password'})
+ >>> request = TestRequest(form={'login': 'max', 'password': 'password'})
>>> authenticated = auth.authenticate(request)
and check your authenticated principal:
@@ -526,10 +526,11 @@
Edge cases
----------
-We can have Users with unicode login, as we allow this with TextLine in IUser.
+We can have Users with unicode logins, as we allow this with TextLine in IUser.
>>> p = User(u'bob'+unichr(233), 'password', 'title')
Adding it should not fail:
>>> uid, user = authPlugin.add(p)
+
More information about the checkins
mailing list