API Reference

Interfaces

Authentication interfaces

exception zope.authentication.interfaces.PrincipalLookupError

Bases: exceptions.LookupError

No principal for given principal id

interface zope.authentication.interfaces.IUnauthenticatedPrincipal

Extends: zope.security.interfaces.IPrincipal

A principal that hasn’t been authenticated.

Authenticated principals are preferable to UnauthenticatedPrincipals.

interface zope.authentication.interfaces.IFallbackUnauthenticatedPrincipal

Extends: zope.authentication.interfaces.IUnauthenticatedPrincipal

Marker interface for the fallback unauthenticated principal.

This principal can be used by publications to set on a request if no principal, not even an unauthenticated principal, was returned by any authentication utility to fulfill the contract of IApplicationRequest.

interface zope.authentication.interfaces.IUnauthenticatedGroup

Extends: zope.security.interfaces.IGroup

A group containing unauthenticated users

interface zope.authentication.interfaces.IAuthenticatedGroup

Extends: zope.security.interfaces.IGroup

A group containing authenticated users

interface zope.authentication.interfaces.IEveryoneGroup

Extends: zope.security.interfaces.IGroup

A group containing all users

interface zope.authentication.interfaces.IAuthentication

Provide support for establishing principals for requests.

This is implemented by performing protocol-specific actions, such as issuing challenges or providing login interfaces.

IAuthentication objects are used to implement authentication utilities. Because they implement utilities, they are expected to collaborate with utilities in other contexts. Client code doesn’t search a context and call multiple utilities. Instead, client code will call the most specific utility in a place and rely on the utility to delegate to other utilities as necessary.

The interface doesn’t include methods for data management. Utilities may use external data and not allow management in Zope. Simularly, the data to be managed may vary with different implementations of a utility.

authenticate(request)

Identify a principal for a request.

If a principal can be identified, then return the principal. Otherwise, return None.

The request object is fairly opaque. We may decide that it implements some generic request interface.

Note

Implementation note: It is likely that the component will dispatch to another component based on the actual request interface. This will allow different kinds of requests to be handled correctly.

For example, a component that authenticates based on user names and passwords might request an adapter for the request as in:

getpw = getAdapter(request, context=self)

The context keyword argument is used to control where the ILoginPassword component is searched for. This is necessary because requests are placeless.

unauthenticatedPrincipal()

Return the unauthenticated principal, if one is defined.

Return None if no unauthenticated principal is defined.

The unauthenticated principal must provide IUnauthenticatedPrincipal.

unauthorized(id, request)

Signal an authorization failure.

This method is called when an auhorization problem occurs. It can perform a variety of actions, such as issuing an HTTP authentication challenge or displaying a login interface.

Note that the authentication utility nearest to the requested resource is called. It is up to authentication utility implementations to collaborate with utilities higher in the object hierarchy.

If no principal has been identified, id will be None.

getPrincipal(id)

Get principal meta-data.

Returns an object of type IPrincipal for the given principal id. A PrincipalLookupError is raised if the principal cannot be found.

Note that the authentication utility nearest to the requested resource is called. It is up to authentication utility implementations to collaborate with utilities higher in the object hierarchy.

interface zope.authentication.interfaces.ILoginPassword

A password based login.

An IAuthentication utility may use this (adapting a request), to discover the login/password passed from the user, or to indicate that a login is required.

getLogin()

Return login name, or None if no login name found.

getPassword()

Return password, or None if no login name found.

If there’s a login but no password, return empty string.

needLogin(realm)

Indicate that a login is needed.

The realm argument is the name of the principal registry.

interface zope.authentication.interfaces.IPrincipalSource

Extends: zope.schema.interfaces.ISource

A Source of Principal Ids

interface zope.authentication.interfaces.ILogout

Provides support for logging out.

logout(request)

Perform a logout.

interface zope.authentication.interfaces.ILogoutSupported

A marker indicating that the security configuration supports logout.

Provide an adapter to this interface to signal that the security system supports logout.

Principals

Principal source and helper function

zope.authentication.principal.checkPrincipal(context, principal_id)

An utility function to check if there’s a principal for given principal id.

Raises ValueError when principal doesn’t exists for given context and principal id.

To test it, let’s create and register a dummy authentication utility.

>>> from zope.authentication.interfaces import IAuthentication
>>> from zope.authentication.interfaces import PrincipalLookupError
>>> from zope.interface import implementer
>>> @implementer(IAuthentication)
... class DummyUtility(object):
...
...     def getPrincipal(self, id):
...         if id == 'bob':
...             return id
...         raise PrincipalLookupError(id)

>>> from zope.component import provideUtility
>>> provideUtility(DummyUtility())

Now, let’s check the behaviour of this function.

>>> from zope.authentication.principal import checkPrincipal
>>> checkPrincipal(None, 'bob')
>>> checkPrincipal(None, 'dan')
Traceback (most recent call last):
...
ValueError: ('Undefined principal id', 'dan')

class zope.authentication.principal.PrincipalSource

Bases: object

Generic Principal Source

Implements zope.authentication.interfaces.IPrincipalSource and zope.schema.interfaces.ISourceQueriables.

__contains__(id)

Test for the existence of a user.

We want to check whether the system knows about a particular principal, which is referenced via its id. The source will go through the most local authentication utility to look for the principal. Whether the utility consults other utilities to give an answer is up to the utility itself.

First we need to create a dummy utility that will return a user, if the id is ‘bob’.

>>> from zope.authentication.interfaces import IAuthentication
>>> from zope.interface import implementer
>>> @implementer(IAuthentication)
... class DummyUtility(object):
...     def getPrincipal(self, id):
...         if id == 'bob':
...             return id
...         raise PrincipalLookupError(id)

Let’s register our dummy auth utility.

>>> from zope.component import provideUtility
>>> provideUtility(DummyUtility())

Now initialize the principal source and test the method

>>> from zope.authentication.principal import PrincipalSource
>>> source = PrincipalSource()
>>> 'jim' in source
False
>>> 'bob' in source
True

getQueriables()

Returns an iteratable of queriables.

Queriables are responsible for providing interfaces to search for principals by a set of given parameters (can be different for the various queriables). This method will walk up through all of the authentication utilities to look for queriables.

>>> from zope.schema.interfaces import ISourceQueriables
>>> @implementer(IAuthentication)
... class DummyUtility1(object):
...     __parent__ = None
...     def __repr__(self): return 'dummy1'
>>> dummy1 = DummyUtility1()

>>> @implementer(ISourceQueriables, IAuthentication)
... class DummyUtility2(object):
...     __parent__ = None
...     def getQueriables(self):
...         return ('1', 1), ('2', 2), ('3', 3)
>>> dummy2 = DummyUtility2()

>>> @implementer(IAuthentication)
... class DummyUtility3(DummyUtility2):
...     def getQueriables(self):
...         return ('4', 4),
>>> dummy3 = DummyUtility3()

>>> from zope.authentication.tests.utils import testingNextUtility
>>> testingNextUtility(dummy1, dummy2, IAuthentication)
>>> testingNextUtility(dummy2, dummy3, IAuthentication)

>>> from zope.component import provideUtility
>>> provideUtility(dummy1)

>>> from zope.authentication.principal import PrincipalSource
>>> source = PrincipalSource()
>>> list(source.getQueriables())
[(u'0', dummy1), (u'1.1', 1), (u'1.2', 2), (u'1.3', 3), (u'2.4', 4)]

class zope.authentication.principal.PrincipalTerms(context, request)

Bases: object

Implementation of zope.browser.interfaces.ITerms given a zope.authentication.interfaces.IPrincipalSource and request object.

getTerm(principal_id)

Return a PrincipalTerm for the given ID.

If no such principal can be found, raises LooupError.

getValue(token)

Return the principal ID given its token.

class zope.authentication.principal.PrincipalTerm(token, title)

Bases: object

A principal term.

We have a token based on the encoded principal ID, and a title.

Login

Login/Password provider.

class zope.authentication.loginpassword.LoginPassword(login, password)

Bases: object

Basic zope.authentication.interfaces.ILoginPassword implementation.

This class can be used as a base for implementing ILoginPassword adapters.

Logout

ILogout implementations

class zope.authentication.logout.NoLogout(auth)

Bases: object

An adapter for IAuthentication utilities that don’t implement ILogout.

logout(request)

Does nothing.

class zope.authentication.logout.LogoutSupported(dummy)

Bases: object

A class that can be registered as an adapter to flag logout support.