zope.app.authentication 3.4.3

Detailed Documentation

Authentication

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

• Credentials Plugins

• Authenticator Plugins

Credentials plugins are responsible for extracting user credentials from a request. A credentials plugin may in some cases issue a ‘challenge’ to obtain credentials. For example, a ‘session’ credentials plugin reads credentials from a session (the “extraction”). If it cannot find credentials, it will redirect the user to a login form in order to provide them (the “challenge”).

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 PAU returns a principal object, if it can. The PAU 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 PAU 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.

>>> from zope import interface
>>> from zope.app.authentication import interfaces

>>> class MyCredentialsPlugin(object):
...
...     interface.implements(interfaces.ICredentialsPlugin)
...
...     def extractCredentials(self, request):
...         return request.get('credentials')
...
...     def challenge(self, request):
...         pass # challenge is a no-op for this plugin
...
...     def logout(self, request):
...         pass # logout is a no-op for this plugin

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

>>> class PrincipalInfo(object):
...
...     interface.implements(interfaces.IPrincipalInfo)
...
...     def __init__(self, id, title, description):
...         self.id = id
...         self.title = title
...         self.description = description
...
...     def __repr__(self):
...         return 'PrincipalInfo(%r)' % self.id

>>> class MyAuthenticatorPlugin(object):
...
...     interface.implements(interfaces.IAuthenticatorPlugin)
...
...     def authenticateCredentials(self, credentials):
...         if credentials == 'secretcode':
...             return PrincipalInfo('bob', 'Bob', '')
...
...     def principalInfo(self, id):
...         pass # plugin not currently supporting search

>>> myAuthenticatorPlugin = MyAuthenticatorPlugin()
>>> provideUtility(myAuthenticatorPlugin, name='My Authenticator Plugin')

>>> from zope.app.authentication import principalfolder
>>> provideAdapter(principalfolder.AuthenticatedPrincipalFactory)
>>> provideAdapter(principalfolder.FoundPrincipalFactory)

>>> from zope.app import authentication
>>> pau = authentication.PluggableAuthentication('xyz_')

>>> pau.credentialsPlugins = ('My Credentials Plugin', )
>>> pau.authenticatorPlugins = ('My Authenticator Plugin', )

>>> from zope.publisher.browser import TestRequest
>>> print pau.authenticate(TestRequest())
None

>>> print pau.authenticate(TestRequest(credentials='let me in!'))
None

>>> request = TestRequest(credentials='secretcode')
>>> principal = pau.authenticate(request)
>>> principal
Principal('xyz_bob')

>>> [event] = getEvents(interfaces.IAuthenticatedPrincipalCreated)
>>> event.principal is principal
True
>>> event.info
PrincipalInfo('bob')
>>> event.request is request
True

>>> event.info.title
'Bob'
>>> event.info.id # does not include pau prefix
'bob'
>>> event.info.description
''

>>> event.info.credentialsPlugin is myCredentialsPlugin
True
>>> event.info.authenticatorPlugin is myAuthenticatorPlugin
True

>>> def add_info(event):
...     event.principal.title = event.info.title
>>> subscribe([interfaces.IAuthenticatedPrincipalCreated], None, add_info)

>>> principal = pau.authenticate(request)
>>> principal.title
'Bob'

>>> class MyAuthenticatorPlugin2(MyAuthenticatorPlugin):
...
...     def authenticateCredentials(self, credentials):
...         if credentials == 'secretcode':
...             return PrincipalInfo('black', 'Black Spy', '')
...         elif credentials == 'hiddenkey':
...             return PrincipalInfo('white', 'White Spy', '')

>>> provideUtility(MyAuthenticatorPlugin2(), name='My Authenticator Plugin 2')

>>> pau.authenticatorPlugins = (
...     'My Authenticator Plugin 2',
...     'My Authenticator Plugin')

>>> pau.authenticate(TestRequest(credentials='secretcode'))
Principal('xyz_black')

>>> print pau.authenticate(TestRequest(credentials='let me in!!'))
None

>>> pau.authenticatorPlugins = (
...     'My Authenticator Plugin',
...     'My Authenticator Plugin 2')

>>> pau.authenticate(TestRequest(credentials='secretcode'))
Principal('xyz_bob')

>>> pau.authenticate(TestRequest(credentials='hiddenkey'))
Principal('xyz_white')

>>> class FormCredentialsPlugin:
...
...     interface.implements(interfaces.ICredentialsPlugin)
...
...     def extractCredentials(self, request):
...         return request.form.get('my_credentials')
...
...     def challenge(self, request):
...         pass
...
...     def logout(request):
...         pass

>>> provideUtility(FormCredentialsPlugin(),
...                name='Form Credentials Plugin')

>>> pau.credentialsPlugins = (
...     'Form Credentials Plugin',
...     'My Credentials Plugin')

>>> pau.authenticate(TestRequest(credentials='secretcode',
...                              form={'my_credentials': 'hiddenkey'}))
Principal('xyz_white')

>>> pau.authenticate(TestRequest(credentials='secretcode'))
Principal('xyz_bob')

- Get credentials using 'Form Credentials Plugin'

- Failed to get credentials using 'Form Credentials Plugin', try
  'My Credentials Plugin'

- Got 'scecretcode' credentials using 'My Credentials Plugin', try to
  authenticate using 'My Authenticator Plugin'

- Succeeded in authenticating with 'My Authenticator Plugin'

>>> pau.authenticate(TestRequest(credentials='hiddenkey',
...                              form={'my_credentials': 'bogusvalue'}))
Principal('xyz_white')

Principal Searching

As a component that provides IAuthentication, a PAU lets you lookup a principal with a principal ID. The PAU looks up a principal by delegating to its authenticators. In our example, none of the authenticators implement this search capability, so when we look for a principal:

>>> print pau.getPrincipal('xyz_bob')
Traceback (most recent call last):
PrincipalLookupError: bob

>>> print pau.getPrincipal('white')
Traceback (most recent call last):
PrincipalLookupError: white

>>> print pau.getPrincipal('black')
Traceback (most recent call last):
PrincipalLookupError: black

For a PAU to support search, it needs to be configured with one or more authenticator plugins that support search. To illustrate, we’ll create a new authenticator:

>>> class SearchableAuthenticatorPlugin:
...
...     interface.implements(interfaces.IAuthenticatorPlugin)
...
...     def __init__(self):
...         self.infos = {}
...         self.ids = {}
...
...     def principalInfo(self, id):
...         return self.infos.get(id)
...
...     def authenticateCredentials(self, credentials):
...         id = self.ids.get(credentials)
...         if id is not None:
...             return self.infos[id]
...
...     def add(self, id, title, description, credentials):
...         self.infos[id] = PrincipalInfo(id, title, description)
...         self.ids[credentials] = id

This class is typical of an authenticator plugin. It can both authenticate principals and find principals given a ID. While there are cases where an authenticator may opt to not perform one of these two functions, they are less typical.

As with any plugin, we need to register it as a utility:

>>> searchable = SearchableAuthenticatorPlugin()
>>> provideUtility(searchable, name='Searchable Authentication Plugin')

We’ll now configure the PAU to use only the searchable authenticator:

>>> pau.authenticatorPlugins = ('Searchable Authentication Plugin',)

and add some principals to the authenticator:

>>> searchable.add('bob', 'Bob', 'A nice guy', 'b0b')
>>> searchable.add('white', 'White Spy', 'Sneaky', 'deathtoblack')

Now when we ask the PAU to find a principal:

>>> pau.getPrincipal('xyz_bob')
Principal('xyz_bob')

but only those it knows about:

>>> print pau.getPrincipal('black')
Traceback (most recent call last):
PrincipalLookupError: black

>>> clearEvents()
>>> principal = pau.getPrincipal('xyz_white')
>>> principal
Principal('xyz_white')

>>> [event] = getEvents(interfaces.IFoundPrincipalCreated)
>>> event.principal is principal
True
>>> event.info
PrincipalInfo('white')

>>> event.info.credentialsPlugin is None
True
>>> event.info.authenticatorPlugin is searchable
True

>>> subscribe([interfaces.IFoundPrincipalCreated], None, add_info)

>>> searchable2 = SearchableAuthenticatorPlugin()
>>> provideUtility(searchable2, name='Searchable Authentication Plugin 2')

>>> searchable.add('black', 'Black Spy', 'Also sneaky', 'deathtowhite')

>>> pau.authenticatorPlugins = (
...     'Searchable Authentication Plugin 2',
...     'Searchable Authentication Plugin')

>>> pau.getPrincipal('xyz_white')
Principal('xyz_white')

>>> pau.getPrincipal('xyz_black')
Principal('xyz_black')

>>> searchable2.add('white', 'White Rider', '', 'r1der')
>>> pau.getPrincipal('xyz_white').title
'White Rider'

>>> pau.authenticatorPlugins = (
...     'Searchable Authentication Plugin',
...     'Searchable Authentication Plugin 2')

>>> pau.getPrincipal('xyz_white').title
'White Spy'

Issuing a Challenge

Part of PAU’s IAuthentication contract is to challenge the user for credentials when its ‘unauthorized’ method is called. The need for this functionality is driven by the following use case:

• A user attempts to perform an operation he is not authorized to perform.

• A handler responds to the unauthorized error by calling IAuthentication ‘unauthorized’.

• The authentication component (in our case, a PAU) issues a challenge to the user to collect new credentials (typically in the form of logging in as a new user).

The PAU handles the credentials challenge by delegating to its credentials plugins.

Currently, the PAU is configured with the credentials plugins that don’t perform any action when asked to challenge (see above the ‘challenge’ methods).

To illustrate challenges, we’ll subclass an existing credentials plugin and do something in its ‘challenge’:

>>> class LoginFormCredentialsPlugin(FormCredentialsPlugin):
...
...     def __init__(self, loginForm):
...         self.loginForm = loginForm
...
...     def challenge(self, request):
...         request.response.redirect(self.loginForm)
...         return True

This plugin handles a challenge by redirecting the response to a login form. It returns True to signal to the PAU that it handled the challenge.

We will now create and register a couple of these plugins:

>>> provideUtility(LoginFormCredentialsPlugin('simplelogin.html'),
...                name='Simple Login Form Plugin')

>>> provideUtility(LoginFormCredentialsPlugin('advancedlogin.html'),
...                name='Advanced Login Form Plugin')

and configure the PAU to use them:

>>> pau.credentialsPlugins = (
...     'Simple Login Form Plugin',
...     'Advanced Login Form Plugin')

Now when we call ‘unauthorized’ on the PAU:

>>> request = TestRequest()
>>> pau.unauthorized(id=None, request=request)

we see that the user is redirected to the simple login form:

>>> request.response.getStatus()
302
>>> request.response.getHeader('location')
'simplelogin.html'

We can change the challenge policy by reordering the plugins:

>>> pau.credentialsPlugins = (
...     'Advanced Login Form Plugin',
...     'Simple Login Form Plugin')

Now when we call ‘unauthorized’:

>>> request = TestRequest()
>>> pau.unauthorized(id=None, request=request)

the advanced plugin is used because it’s first:

>>> request.response.getStatus()
302
>>> request.response.getHeader('location')
'advancedlogin.html'

>>> class XChallengeCredentialsPlugin(FormCredentialsPlugin):
...
...     challengeProtocol = 'X-Challenge'
...
...     def __init__(self, challengeValue):
...         self.challengeValue = challengeValue
...
...     def challenge(self, request):
...         value = self.challengeValue
...         existing = request.response.getHeader('X-Challenge', '')
...         if existing:
...             value += ' ' + existing
...         request.response.setHeader('X-Challenge', value)
...         return True

>>> provideUtility(XChallengeCredentialsPlugin('basic'),
...                name='Basic X-Challenge Plugin')

>>> provideUtility(XChallengeCredentialsPlugin('advanced'),
...                name='Advanced X-Challenge Plugin')

>>> pau.credentialsPlugins = (
...     'Basic X-Challenge Plugin',
...     'Advanced X-Challenge Plugin')

>>> request = TestRequest()
>>> pau.unauthorized(None, request)

>>> request.response.getHeader('X-Challenge')
'advanced basic'

Pluggable-Authentication Prefixes

Principal ids are required to be unique system wide. Plugins will often provide options for providing id prefixes, so that different sets of plugins provide unique ids within a PAU. If there are multiple pluggable-authentication utilities in a system, it’s a good idea to give each PAU a unique prefix, so that principal ids from different PAUs don’t conflict. We can provide a prefix when a PAU is created:

>>> pau = authentication.PluggableAuthentication('mypau_')
>>> pau.credentialsPlugins = ('My Credentials Plugin', )
>>> pau.authenticatorPlugins = ('My Authenticator Plugin', )

When we create a request and try to authenticate:

>>> pau.authenticate(TestRequest(credentials='secretcode'))
Principal('mypau_bob')

Note that now, our principal’s id has the pluggable-authentication utility prefix.

We can still lookup a principal, as long as we supply the prefix:

>> pau.getPrincipal('mypas_42')
Principal('mypas_42', "{'domain': 42}")

>> pau.getPrincipal('mypas_41')
OddPrincipal('mypas_41', "{'int': 41}")

Searching

PAU implements ISourceQueriables:

>>> from zope.schema.interfaces import ISourceQueriables
>>> ISourceQueriables.providedBy(pau)
True

This means a PAU can be used in a principal source vocabulary (Zope provides a sophisticated searching UI for principal sources).

As we’ve seen, a PAU uses each of its authenticator plugins to locate a principal with a given ID. However, plugins may also provide the interface IQuerySchemaSearch to indicate they can be used in the PAU’s principal search scheme.

Currently, our list of authenticators:

>>> pau.authenticatorPlugins
('My Authenticator Plugin',)

does not include a queriable authenticator. PAU cannot therefore provide any queriables:

>>> list(pau.getQueriables())
[]

Before we illustrate how an authenticator is used by the PAU to search for principals, we need to setup an adapter used by PAU:

>>> provideAdapter(
...     authentication.authentication.QuerySchemaSearchAdapter,
...     provides=interfaces.IQueriableAuthenticator)

This adapter delegates search responsibility to an authenticator, but prepends the PAU prefix to any principal IDs returned in a search.

Next, we’ll create a plugin that provides a search interface:

>>> class QueriableAuthenticatorPlugin(MyAuthenticatorPlugin):
...
...     interface.implements(interfaces.IQuerySchemaSearch)
...
...     schema = None
...
...     def search(self, query, start=None, batch_size=None):
...         yield 'foo'
...

and install it as a plugin:

>>> plugin = QueriableAuthenticatorPlugin()
>>> provideUtility(plugin,
...                provides=interfaces.IAuthenticatorPlugin,
...                name='Queriable')
>>> pau.authenticatorPlugins += ('Queriable',)

Now, the PAU provides a single queriable:

>>> list(pau.getQueriables()) # doctest: +ELLIPSIS
[('Queriable', ...QuerySchemaSearchAdapter object...)]

We can use this queriable to search for our principal:

>>> queriable = list(pau.getQueriables())[0][1]
>>> list(queriable.search('not-used'))
['mypau_foo']

Note that the resulting principal ID includes the PAU prefix. Were we to search the plugin directly:

>>> list(plugin.search('not-used'))
['foo']

The result does not include the PAU prefix. The prepending of the prefix is handled by the PluggableAuthenticationQueriable.

Queryiable plugins can provide the ILocation interface. In this case the QuerySchemaSearchAdapter’s __parent__ is the same as the __parent__ of the plugin:

>>> import zope.location.interfaces
>>> class LocatedQueriableAuthenticatorPlugin(QueriableAuthenticatorPlugin):
...
...     interface.implements(zope.location.interfaces.ILocation)
...
...     __parent__ = __name__ = None
...
>>> import zope.app.component.hooks
>>> site = zope.app.component.hooks.getSite()
>>> plugin = LocatedQueriableAuthenticatorPlugin()
>>> plugin.__parent__ = site
>>> plugin.__name__ = 'localname'
>>> provideUtility(plugin,
...                provides=interfaces.IAuthenticatorPlugin,
...                name='location-queriable')
>>> pau.authenticatorPlugins = ('location-queriable',)

We have one queriable again:

>>> queriables = list(pau.getQueriables())
>>> queriables  # doctest: +ELLIPSIS
[('location-queriable', ...QuerySchemaSearchAdapter object...)]

The queriable’s __parent__ is the site as set above:

>>> queriable = queriables[0][1]
>>> queriable.__parent__ is site
True

If the queriable provides ILocation but is not actually locatable (i.e. the parent is None) the pau itself becomes the parent:

>>> plugin = LocatedQueriableAuthenticatorPlugin()
>>> provideUtility(plugin,
...                provides=interfaces.IAuthenticatorPlugin,
...                name='location-queriable-wo-parent')
>>> pau.authenticatorPlugins = ('location-queriable-wo-parent',)

We have one queriable again:

>>> queriables = list(pau.getQueriables())
>>> queriables  # doctest: +ELLIPSIS
[('location-queriable-wo-parent', ...QuerySchemaSearchAdapter object...)]

And the parent is the pau:

>>> queriable = queriables[0][1]
>>> queriable.__parent__  # doctest: +ELLIPSIS
<zope.app.authentication.authentication.PluggableAuthentication object ...>
>>> queriable.__parent__ is pau
True

Authentication

Principal folders provide the IAuthenticatorPlugin interface. When we provide suitable credentials:

>>> from zope.testing.doctestunit import pprint
>>> principals.authenticateCredentials({'login': 'login1', 'password': '123'})
PrincipalInfo(u'principal.p1')

We get back a principal id and supplementary information, including the principal title and description. Note that the principal id is a concatenation of the principal-folder prefix and the name of the principal-information object within the folder.

None is returned if the credentials are invalid:

>>> principals.authenticateCredentials({'login': 'login1',
...                                     'password': '1234'})
>>> principals.authenticateCredentials(42)

Search

Principal folders also provide the IQuerySchemaSearch interface. This supports both finding principal information based on their ids:

>>> principals.principalInfo('principal.p1')
PrincipalInfo('principal.p1')

>>> principals.principalInfo('p1')

and searching for principals based on a search string:

>>> list(principals.search({'search': 'other'}))
[u'principal.p2']

>>> list(principals.search({'search': 'OTHER'}))
[u'principal.p2']

>>> list(principals.search({'search': ''}))
[u'principal.p1', u'principal.p2']

>>> list(principals.search({'search': 'eek'}))
[]

>>> list(principals.search({}))
[]

If there are a large number of matches:

>>> for i in range(20):
...     i = str(i)
...     p = InternalPrincipal('l'+i, i, "Dude "+i)
...     principals[i] = p

>>> pprint(list(principals.search({'search': 'D'})))
[u'principal.0',
 u'principal.1',
 u'principal.10',
 u'principal.11',
 u'principal.12',
 u'principal.13',
 u'principal.14',
 u'principal.15',
 u'principal.16',
 u'principal.17',
 u'principal.18',
 u'principal.19',
 u'principal.2',
 u'principal.3',
 u'principal.4',
 u'principal.5',
 u'principal.6',
 u'principal.7',
 u'principal.8',
 u'principal.9']

We can use batching parameters to specify a subset of results:

>>> pprint(list(principals.search({'search': 'D'}, start=17)))
[u'principal.7',
 u'principal.8',
 u'principal.9']

>>> pprint(list(principals.search({'search': 'D'}, batch_size=5)))
[u'principal.0',
 u'principal.1',
 u'principal.10',
 u'principal.11',
 u'principal.12']

>>> pprint(list(principals.search({'search': 'D'}, start=5, batch_size=5)))
[u'principal.13',
 u'principal.14',
 u'principal.15',
 u'principal.16',
 u'principal.17']

There is an additional method that allows requesting the principal id associated with a login id. The method raises KeyError when there is no associated principal:

>>> principals.getIdByLogin("not-there")
Traceback (most recent call last):
KeyError: 'not-there'

If there is a matching principal, the id is returned:

>>> principals.getIdByLogin("login1")
u'principal.p1'

Changing credentials

Credentials can be changed by modifying principal-information objects:

>>> p1.login = 'bob'
>>> p1.password = 'eek'

>>> principals.authenticateCredentials({'login': 'bob', 'password': 'eek'})
PrincipalInfo(u'principal.p1')

>>> principals.authenticateCredentials({'login': 'login1',
...                                     'password': 'eek'})

>>> principals.authenticateCredentials({'login': 'bob',
...                                     'password': '123'})

It is an error to try to pick a login name that is already taken:

>>> p1.login = 'login2'
Traceback (most recent call last):
...
ValueError: Principal Login already taken!

If such an attempt is made, the data are unchanged:

>>> principals.authenticateCredentials({'login': 'bob', 'password': 'eek'})
PrincipalInfo(u'principal.p1')

Removing principals

Of course, if a principal is removed, we can no-longer authenticate it:

>>> del principals['p1']
>>> principals.authenticateCredentials({'login': 'bob',
...                                     'password': 'eek'})

credentialsPlugins

For completeness, we’ll do the same review of the credentialsPlugins.

>>> class DemoPlugin(object):
...     interface.implements(interfaces.ICredentialsPlugin)
...     def __init__(self, name):
...         self.name = name
...
>>> utility_plugins = dict(
...     (i, DemoPlugin(u'Plugin %d' % i)) for i in range(4))
>>> contained_plugins = dict(
...     (i, DemoPlugin(u'Plugin %d' % i)) for i in range(1, 5))
>>> for p in utility_plugins.values():
...     component.provideUtility(p, name=p.name)
...
>>> auth = DemoAuth((p.name, p) for p in contained_plugins.values())
>>> vocab = vocabulary.credentialsPlugins(auth)

Iterating over the vocabulary results in all of the terms, in a relatively arbitrary order of their names. (This vocabulary should typically use a widget that sorts values on the basis of localized collation order of the term titles.) Similarly, we can use in to test for the presence of values in the vocabulary. The length reports the expected value.

>>> [term.value for term in vocab] # doctest: +NORMALIZE_WHITESPACE
[u'Plugin 0', u'Plugin 1', u'Plugin 2', u'Plugin 3', u'Plugin 4',
 u'Plugin X']
>>> ['Plugin %s' % i in vocab for i in range(-1, 6)]
[False, True, True, True, True, True, False]
>>> 'Plugin X' in vocab
True
>>> len(vocab)
6

One can get a term for a given value using getTerm(); its token, in turn, should also return the same effective term from getTermByToken.

>>> values = ['Plugin 0', 'Plugin 1', 'Plugin 2', 'Plugin 3', 'Plugin 4',
...           'Plugin X']
>>> for val in values:
...     term = vocab.getTerm(val)
...     assert term.value == val
...     term2 = vocab.getTermByToken(term.token)
...     assert term2.token == term.token
...     assert term2.value == val
...

The terms have titles, which are message ids that show the plugin title or id and whether the plugin is a utility or just contained in the auth utility. We’ll give one of the plugins a dublin core title just to show the functionality. We need to regenerate the vocabulary, since it calculates all of its data at once. Then we’ll check the titles. We’ll have to translate them to see what we expect.

>>> interface.directlyProvides(contained_plugins[1], ISpecial)
>>> vocab = vocabulary.credentialsPlugins(auth)
>>> pprint.pprint([i18n.translate(term.title) for term in vocab])
[u'Plugin 0 (a utility)',
 u'Special Title (in contents)',
 u'Plugin 2 (in contents)',
 u'Plugin 3 (in contents)',
 u'Plugin 4 (in contents)',
 u'Plugin X (not found; deselecting will remove)']

Version 3.4.3 (2008-08-07)

• no changes. Retag for correct release on PyPI

Version 3.4.2 (2008-07-09)

• Make it compatible with zope.app.container 3.6.1 and 3.5.4 changes, Changed super(BTreeContainer, self).__init__() to super(GroupFolder, self).__init__() in GroupFolder class.

Version 3.4.1 (2007-10-24)

• avoid deprecation warning

Version 3.4.0 (2007-10-11)

• Updated package meta-data.

Version 3.4.0b1 (2007-09-27)

• First Zope-independent release.