Package: zope.app.authentication
This package provides a flexible and pluggable authentication utility for Zope
3, usingzope.pluggableauth. Several common plugins are provided.ContentsPluggable-Authentication UtilityAuthenticationSimple Credentials PluginSimple Authenticator PluginPrincipal FactoriesConfiguring a PAUUsing the PAU to AuthenticateAuthenticated Principal Creates EventsMultiple Authenticator PluginsMultiple Credentials PluginsPrincipal SearchingFound Principal Creates EventsMultiple Authenticator PluginsIssuing a ChallengeChallenge ProtocolsPluggable-Authentication PrefixesSearchingPrincipal FolderAuthenticationSearchChanging credentialsRemoving principalsVocabulariescredentialsPluginsChanges5.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 UtilityThe 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 thezope.authentication.interfaces.IAuthenticationinterface.AuthenticationThe primary job of PAU is to authenticate principals. It uses two types of
plug-ins in its work:Credentials PluginsAuthenticator PluginsCredentials 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 PluginTo 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 pluginAs a plugin, MyCredentialsPlugin needs to be registered as a named utility:>>> myCredentialsPlugin = MyCredentialsPlugin()
>>> provideUtility(myCredentialsPlugin, name='My Credentials Plugin')Simple Authenticator PluginNext 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.idOur 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 searchAs with the credentials plugin, the authenticator plugin must be registered
as a named utility:>>> myAuthenticatorPlugin = MyAuthenticatorPlugin()
>>> provideUtility(myAuthenticatorPlugin, name='My Authenticator Plugin')Principal FactoriesWhile 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 PAUFinally, 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 AuthenticateWe can now use the PAU to authenticate a sample request:>>> from zope.publisher.browser import TestRequest
>>> print(pau.authenticate(TestRequest()))
NoneIn 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!')))
NoneHowever, 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 EventsWe 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
TrueThe 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
TrueNormally, 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 PluginsThe 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!!')))
NoneWhen 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 PluginsAs 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 credentialsGet 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 SearchingAs 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: blackFor 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] = idThis 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: blackFound Principal Creates EventsAs 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
TrueAs 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 PluginsAs 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 ChallengePart 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 TrueThis 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 ProtocolsSometimes, 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 achallengeProtocolattribute that effectively
groups related plugins together for challenging. If a plugin returnsTruefrom 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 Trueand 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 PrefixesPrincipal 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}")SearchingPAU implements ISourceQueriables:>>> from zope.schema.interfaces import ISourceQueriables
>>> ISourceQueriables.providedBy(pau)
TrueThis 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
TrueIf 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
TruePrincipal FolderPrincipal folders contain principal-information objects that contain principal
information. We create an internal principal using theInternalPrincipalclass:>>> 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'] = p2AuthenticationPrincipal folders provide theIAuthenticatorPlugininterface. 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)SearchPrincipal 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 credentialsCredentials 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 principalsOf course, if a principal is removed, we can no-longer authenticate it:>>> del principals['p1']
>>> principals.authenticateCredentials({'login': 'bob',
...                                     'password': 'eek'})VocabulariesThe 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 useinto 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
TrueThe length reports the expected value.>>> len(vocab)
6One can get a term for a given value usinggetTerm(); its token, in
turn, should also return the same effective term fromgetTermByToken.>>> 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)']credentialsPluginsFor 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 useinto 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)
6One can get a term for a given value usinggetTerm(); its token, in
turn, should also return the same effective term fromgetTermByToken.>>> 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)']Changes5.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’sdoctestmodule instead of deprecatedzope.testing.doctest[unit].Moved the following views fromzope.app.securitypolicyhere, to inverse
dependency between these two packages, aszope.app.securitypolicydeprecated in ZTK 1.0:@@grant.html@@AllRolePermissions.html@@RolePermissions.html@@RolesWithPermission.html3.7.1 (2010-02-11)Using the newprincipalfactories.zcmlfile, fromzope.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 tozope.securitypolicyupdate.Don’t usezope.app.testing.ztapiin 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 theloginForm.htmlview. Now the logic is contained in thezope.app.authentication.browser.loginform.LoginFormclass.Fix login form redirection failure in some cases with Python 2.6.Use the newzope.authenticationpackage instead ofzope.app.security.The “Password Manager Names” vocabulary and simple password manager registry
were moved to thezope.passwordpackage.Remove deprecated code.3.5.0 (2009-03-06)Split password manager functionality off to the newzope.passwordpackage. Backward-compatibility imports are left in place.Usezope.siteinstead ofzope.app.component. (Browser code still
needszope.app.componentas 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)Usezope.containerinstead ofzope.app.container. (Browser code
still needszope.app.containeras 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 formd5andshaon 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,
Changedsuper(BTreeContainer,self).__init__()tosuper(GroupFolder,self).__init__()inGroupFolderclass.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.