zope.app.authentication 5.0

Principals and groups management for the pluggable authentication utility

This package provides a flexible and pluggable authentication utility for Zope 3, using zope.pluggableauth. Several common plugins are provided.

Contents

• Pluggable-Authentication Utility

  • Authentication

    • Simple Credentials Plugin

    • Simple Authenticator Plugin

    • Principal Factories

    • Configuring a PAU

    • Using the PAU to Authenticate

    • Authenticated Principal Creates Events

    • Multiple Authenticator Plugins

    • Multiple Credentials Plugins

  • Principal Searching

    • Found Principal Creates Events

    • Multiple Authenticator Plugins

  • Issuing a Challenge

    • Challenge Protocols

  • Pluggable-Authentication Prefixes

  • Searching

• Principal Folder

  • Authentication

  • Search

  • Changing credentials

  • Removing principals

• Vocabularies

  • credentialsPlugins

• Changes

  • 5.0 (2023-02-09)

  • 4.0.0 (2017-05-02)

  • 3.9 (2010-10-18)

  • 3.8.0 (2010-09-25)

  • 3.7.1 (2010-02-11)

  • 3.7.0 (2010-02-08)

  • 3.6.2 (2010-01-05)

  • 3.6.1 (2009-10-07)

  • 3.6.0 (2009-03-14)

  • 3.5.0 (2009-03-06)

  • 3.5.0a2 (2009-02-01)

  • 3.5.0a1 (2009-01-31)

  • 3.4.4 (2008-12-12)

  • 3.4.3 (2008-08-07)

  • 3.4.2 (2008-07-09)

  • 3.4.1 (2007-10-24)

  • 3.4.0 (2007-10-11)

  • 3.4.0b1 (2007-09-27)

Pluggable-Authentication Utility

The Pluggable-Authentication Utility (PAU) provides a framework for authenticating principals and associating information with them. It uses plugins and subscribers to get its work done.

For a pluggable-authentication utility to be used, it should be registered as a utility providing the zope.authentication.interfaces.IAuthentication interface.

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.

Simple Credentials Plugin

To illustrate, we’ll create a simple credentials plugin:

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

>>> @interface.implementer(interfaces.ICredentialsPlugin)
... class MyCredentialsPlugin(object):
...
...
...     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

As a plugin, MyCredentialsPlugin needs to be registered as a named utility:

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

Simple Authenticator Plugin

Next we’ll create a simple authenticator plugin. For our plugin, we’ll need an implementation of IPrincipalInfo:

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

Our authenticator uses this type when it creates a principal info:

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

As with the credentials plugin, the authenticator plugin must be registered as a named utility:

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

Principal Factories

While authenticator plugins provide principal info, they are not responsible for creating principals. This function is performed by factory adapters. For these tests we’ll borrow some factories from the principal folder:

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

For more information on these factories, see their docstrings.

Configuring a PAU

Finally, we’ll create the PAU itself:

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

and configure it with the two plugins:

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

Using the PAU to Authenticate

We can now use the PAU to authenticate a sample request:

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

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:

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

However, if we provide the proper credentials:

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

we get an authenticated principal.

Authenticated Principal Creates Events

We can verify that the appropriate event was published:

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

The info object has the id, title, and description of the principal. The info object is also generated by the authenticator plugin, so the plugin may itself have provided additional information on the info object:

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

It is also decorated with two other attributes, credentialsPlugin and authenticatorPlugin: these are the plugins used to extract credentials for and authenticate this principal. These attributes can be useful for subscribers that want to react to the plugins used. For instance, subscribers can determine that a given credential plugin does or does not support logout, and provide information usable to show or hide logout user interface:

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

Normally, we provide subscribers to these events that add additional information to the principal. For example, we’ll add one that sets the title:

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

Now, if we authenticate a principal, its title is set:

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

Multiple Authenticator Plugins

The PAU works with multiple authenticator plugins. It uses each plugin, in the order specified in the PAU’s authenticatorPlugins attribute, to authenticate a set of credentials.

To illustrate, we’ll create another authenticator:

>>> 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')

If we put it before the original authenticator:

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

Then it will be given the first opportunity to authenticate a request:

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

If neither plugins can authenticate, pau returns None:

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

When we change the order of the authenticator plugins:

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

we see that our original plugin is now acting first:

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

The second plugin, however, gets a chance to authenticate if first does not:

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

Multiple Credentials Plugins

As with with authenticators, we can specify multiple credentials plugins. To illustrate, we’ll create a credentials plugin that extracts credentials from a request form:

>>> @interface.implementer(interfaces.ICredentialsPlugin)
... class FormCredentialsPlugin:
...
...     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')

and insert the new credentials plugin before the existing plugin:

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

The PAU will use each plugin in order to try and obtain credentials from a request:

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

In this case, the first credentials plugin succeeded in getting credentials from the form and the second authenticator was able to authenticate the credentials. Specifically, the PAU went through these steps:

• Get credentials using ‘Form Credentials Plugin’

• Got ‘hiddenkey’ credentials using ‘Form Credentials Plugin’, try to authenticate using ‘My Authenticator Plugin’

• Failed to authenticate ‘hiddenkey’ with ‘My Authenticator Plugin’, try ‘My Authenticator Plugin 2’

• Succeeded in authenticating with ‘My Authenticator Plugin 2’

Let’s try a different scenario:

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

In this case, the PAU went through these steps:

- 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'

Let’s try a slightly more complex scenario:

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

This highlights PAU’s ability to use multiple plugins for authentication:

• Get credentials using ‘Form Credentials Plugin’

• Got ‘bogusvalue’ credentials using ‘Form Credentials Plugin’, try to authenticate using ‘My Authenticator Plugin’

• Failed to authenticate ‘boguskey’ with ‘My Authenticator Plugin’, try ‘My Authenticator Plugin 2’

• Failed to authenticate ‘boguskey’ with ‘My Authenticator Plugin 2’ – there are no more authenticators to try, so lets try the next credentials plugin for some new credentials

• Get credentials using ‘My Credentials Plugin’

• Got ‘hiddenkey’ credentials using ‘My Credentials Plugin’, try to authenticate using ‘My Authenticator Plugin’

• Failed to authenticate ‘hiddenkey’ using ‘My Authenticator Plugin’, try ‘My Authenticator Plugin 2’

• Succeeded in authenticating with ‘My Authenticator Plugin 2’ (shouts and cheers!)

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):
zope.authentication.interfaces.PrincipalLookupError: bob

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

>>> print(pau.getPrincipal('black'))
Traceback (most recent call last):
zope.authentication.interfaces.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:

>>> @interface.implementer(interfaces.IAuthenticatorPlugin)
... class SearchableAuthenticatorPlugin:
...
...     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):
zope.authentication.interfaces.PrincipalLookupError: black

Found Principal Creates Events

As evident in the authenticator’s ‘createFoundPrincipal’ method (see above), a FoundPrincipalCreatedEvent is published when the authenticator finds a principal on behalf of PAU’s ‘getPrincipal’:

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

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

The info has an authenticatorPlugin, but no credentialsPlugin, since none was used:

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

As we have seen with authenticated principals, it is common to subscribe to principal created events to add information to the newly created principal. In this case, we need to subscribe to IFoundPrincipalCreated events:

>>> provideHandler(add_info, [interfaces.IFoundPrincipalCreated])

Now when a principal is created as a result of a search, it’s title and description will be set (by the add_info handler function).

Multiple Authenticator Plugins

As with the other operations we’ve seen, the PAU uses multiple plugins to find a principal. If the first authenticator plugin can’t find the requested principal, the next plugin is used, and so on.

To illustrate, we’ll create and register a second searchable authenticator:

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

and add a principal to it:

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

When we configure the PAU to use both searchable authenticators (note the order):

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

we see how the PAU uses both plugins:

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

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

If more than one plugin know about the same principal ID, the first plugin is used and the remaining are not delegated to. To illustrate, we’ll add another principal with the same ID as an existing principal:

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

If we change the order of the plugins:

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

we get a different principal for ID ‘white’:

>>> 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'

Challenge Protocols

Sometimes, we want multiple challengers to work together. For example, the HTTP specification allows multiple challenges to be issued in a response. A challenge plugin can provide a challengeProtocol attribute that effectively groups related plugins together for challenging. If a plugin returns True from its challenge and provides a non-None challengeProtocol, subsequent plugins in the credentialsPlugins list that have the same challenge protocol will also be used to challenge.

Without a challengeProtocol, only the first plugin to succeed in a challenge will be used.

Let’s look at an example. We’ll define a new plugin that specifies an ‘X-Challenge’ protocol:

>>> 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

and register a couple instances as utilities:

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

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

When we use both plugins with the PAU:

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

and call ‘unauthorized’:

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

we see that both plugins participate in the challange, rather than just the first plugin:

>>> 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:

>>> import zope.app.authentication.authentication
>>> 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:

>>> @interface.implementer(interfaces.IQuerySchemaSearch)
... class QueriableAuthenticatorPlugin(MyAuthenticatorPlugin):
...
...     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
>>> @interface.implementer(zope.location.interfaces.ILocation)
... class LocatedQueriableAuthenticatorPlugin(QueriableAuthenticatorPlugin):
...
...     __parent__ = __name__ = None
...
>>> import zope.component.hooks
>>> site = zope.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.pluggableauth.authentication.PluggableAuthentication object ...>
>>> queriable.__parent__ is pau
True

Principal Folder

Principal folders contain principal-information objects that contain principal information. We create an internal principal using the InternalPrincipal class:

>>> from zope.app.authentication.principalfolder import InternalPrincipal
>>> p1 = InternalPrincipal('login1', '123', "Principal 1",
...     passwordManagerName="SHA1")
>>> p2 = InternalPrincipal('login2', '456', "The Other One")

and add them to a principal folder:

>>> from zope.app.authentication.principalfolder import PrincipalFolder
>>> principals = PrincipalFolder('principal.')
>>> principals['p1'] = p1
>>> principals['p2'] = p2

Authentication

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

>>> from pprint 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'})

Vocabularies

The vocabulary module provides vocabularies for the authenticator plugins and the credentials plugins.

The options should include the unique names of all of the plugins that provide the appropriate interface (interfaces.ICredentialsPlugin or interfaces.IAuthentiatorPlugin, respectively) for the current context– which is expected to be a pluggable authentication utility, hereafter referred to as a PAU.

These names may be for objects contained within the PAU (“contained plugins”), or may be utilities registered for the specified interface, found in the context of the PAU (“utility plugins”). Contained plugins mask utility plugins of the same name. They also may be names currently selected in the PAU that do not actually have a corresponding plugin at this time.

Here is a short example of how the vocabulary should work. Let’s say we’re working with authentication plugins. We’ll create some faux authentication plugins, and register some of them as utilities and put others in a faux PAU.

>>> from zope.app.authentication import interfaces
>>> from zope import interface, component
>>> @interface.implementer(interfaces.IAuthenticatorPlugin)
... class DemoPlugin(object):
...
...     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))
>>> sorted(utility_plugins.keys())
[0, 1, 2, 3]
>>> for p in utility_plugins.values():
...     component.provideUtility(p, name=p.name)
...
>>> sorted(contained_plugins.keys()) # 1 will mask utility plugin 1
[1, 2, 3, 4]
>>> @interface.implementer(interfaces.IPluggableAuthentication)
... class DemoAuth(dict):
...
...     def __init__(self, *args, **kwargs):
...         super(DemoAuth, self).__init__(*args, **kwargs)
...         self.authenticatorPlugins = (u'Plugin 3', u'Plugin X')
...         self.credentialsPlugins = (u'Plugin 4', u'Plugin X')
...
>>> auth = DemoAuth((p.name, p) for p in contained_plugins.values())

>>> @component.adapter(interface.Interface)
... @interface.implementer(component.IComponentLookup)
... def getSiteManager(context):
...     return component.getGlobalSiteManager()
...
>>> component.provideAdapter(getSiteManager)

We are now ready to create a vocabulary that we can use. The context is our faux authentication utility, auth.

>>> from zope.app.authentication import vocabulary
>>> vocab = vocabulary.authenticatorPlugins(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.)

>>> [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']

Similarly, we can use in to test for the presence of values in the vocabulary.

>>> ['Plugin %s' % i in vocab for i in range(-1, 6)]
[False, True, True, True, True, True, False]
>>> 'Plugin X' in vocab
True

The length reports the expected value.

>>> 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.

>>> import zope.dublincore.interfaces
>>> class ISpecial(interface.Interface):
...     pass
...
>>> interface.directlyProvides(contained_plugins[1], ISpecial)
>>> @interface.implementer(zope.dublincore.interfaces.IDCDescriptiveProperties)
... @component.adapter(ISpecial)
... class DemoDCAdapter(object):
...     def __init__(self, context):
...         pass
...     title = u'Special Title'
...
>>> component.provideAdapter(DemoDCAdapter)

We need to regenerate the vocabulary, since it calculates all of its data at once.

>>> vocab = vocabulary.authenticatorPlugins(auth)

Now we’ll check the titles. We’ll have to translate them to see what we expect.

>>> from zope import i18n
>>> import pprint
>>> 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)']

credentialsPlugins

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

>>> @interface.implementer(interfaces.ICredentialsPlugin)
... class DemoPlugin(object):
...
...     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)']

Changes

5.0 (2023-02-09)

• Drop support for Python 2.7, 3.3, 3.4, 3.5, 3.6.

• Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.

4.0.0 (2017-05-02)

• Drop test dependency on zope.app.zcmlfiles and zope.app.testing.

• Drop explicit dependency on ZODB3.

• Add support for Python 3.4, 3.5 and 3.6, and PyPy.

3.9 (2010-10-18)

• Move concrete IAuthenticatorPlugin implementations to zope.pluggableauth.plugins. Leave backwards compatibility imports.

• Use zope.formlib throughout to lift the dependency on zope.app.form. As it turns out, zope.app.form is still a indirect test dependency though.

3.8.0 (2010-09-25)

• Using python’s doctest module instead of deprecated zope.testing.doctest[unit].

• Moved the following views from zope.app.securitypolicy here, to inverse dependency between these two packages, as zope.app.securitypolicy deprecated in ZTK 1.0:

  • @@grant.html

  • @@AllRolePermissions.html

  • @@RolePermissions.html

  • @@RolesWithPermission.html

3.7.1 (2010-02-11)

• Using the new principalfactories.zcml file, from zope.pluggableauth, to avoid duplication errors, in the adapters registration.

3.7.0 (2010-02-08)

• The Pluggable Authentication utility has been severed and released in a standalone package: zope.pluggableauth. We are now using this new package, providing backward compatibility imports to assure a smooth transition.

3.6.2 (2010-01-05)

• Fix tests by using zope.login, and require new zope.publisher 3.12.

3.6.1 (2009-10-07)

• Fix ftesting.zcml due to zope.securitypolicy update.

• Don’t use zope.app.testing.ztapi in tests, use zope.component’s testing functions instead.

• Fix functional tests and stop using port 8081. Redirecting to different port without trusted flag is not allowed.

3.6.0 (2009-03-14)

• Separate the presentation template and camefrom/redirection logic for the loginForm.html view. Now the logic is contained in the zope.app.authentication.browser.loginform.LoginForm class.

• Fix login form redirection failure in some cases with Python 2.6.

• Use the new zope.authentication package instead of zope.app.security.

• The “Password Manager Names” vocabulary and simple password manager registry were moved to the zope.password package.

• Remove deprecated code.

3.5.0 (2009-03-06)

• Split password manager functionality off to the new zope.password package. Backward-compatibility imports are left in place.

• Use zope.site instead of zope.app.component. (Browser code still needs zope.app.component as it depends on view classes of this package.)

3.5.0a2 (2009-02-01)

• Make old encoded passwords really work.

3.5.0a1 (2009-01-31)

• Use zope.container instead of zope.app.container. (Browser code still needs zope.app.container as it depends on view classes of this package.)

• Encoded passwords are now stored with a prefix ({MD5}, {SHA1}, {SSHA}) indicating the used encoding schema. Old (encoded) passwords can still be used.

• Add an SSHA password manager that is compatible with standard LDAP passwords. As this encoding gives better security agains dictionary attacks, users are encouraged to switch to this new password schema.

• InternalPrincipal now uses SSHA password manager by default.

3.4.4 (2008-12-12)

• Depend on zope.session instead of zope.app.session. The first one currently has all functionality we need.

• Fix deprecation warnings for md5 and sha on Python 2.6.

3.4.3 (2008-08-07)

• No changes. Retag for correct release on PyPI.

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.

3.4.1 (2007-10-24)

• Avoid deprecation warning.

3.4.0 (2007-10-11)

• Updated package meta-data.

3.4.0b1 (2007-09-27)

• First release independent of Zope.