zope.principalregistry

This package provides an authentication utility for zope.authentication that uses a simple non-persistent principal registry. This is typically registered as a global utility, and it is usually configured in ZCML.

Documentation is hosted at https://zopeprincipalregistry.readthedocs.io

Global principal definition

Global principals are defined via ZCML and are placed in zope.principalregistry.principalregistry.principalRegistry. There are several kinds of principals that can be defined.

When you use ZCML to configure this package (load its configure.zcml) that registry becomes a global utility implementing zope.authentication.interfaces.IAuthentication.

Authenticated Users

There are principals that can log in:

>>> zcml("""
...    <configure xmlns="http://namespaces.zope.org/zope">
...
...      <principal
...         id="zope.manager"
...         title="Manager"
...         description="System Manager"
...         login="admin"
...         password_manager="SHA1"
...         password="40bd001563085fc35165329ea1ff5c5ecbdbbeef"
...         />
...
...    </configure>
... """)

>>> from zope.principalregistry.principalregistry import principalRegistry
>>> [p] = principalRegistry.getPrincipals('')
>>> p.id, p.title, p.description, p.getLogin(), p.validate('123')
('zope.manager', u'Manager', u'System Manager', u'admin', True)

We can verify that it conforms to the zope.security.interfaces.IPrincipal interface:

>>> from zope.security.interfaces import IPrincipal
>>> from zope.interface.verify import verifyObject
>>> from zope.schema import getValidationErrors
>>> verifyObject(IPrincipal, p)
True
>>> getValidationErrors(IPrincipal, p)
[]

In fact, it’s actually a zope.security.interfaces.IGroupAwarePrincipal:

>>> from zope.security.interfaces import IGroupAwarePrincipal
>>> verifyObject(IGroupAwarePrincipal, p)
True
>>> getValidationErrors(IGroupAwarePrincipal, p)
[]

The unauthenticated principal

There is the unauthenticated principal:

>>> zcml("""
...    <configure
...        xmlns="http://namespaces.zope.org/zope"
...        >
...
...      <unauthenticatedPrincipal
...         id="zope.unknown"
...         title="Anonymous user"
...         description="A person we don't know"
...         />
...
...    </configure>
... """)

>>> p = principalRegistry.unauthenticatedPrincipal()
>>> p.id, p.title, p.description
('zope.unknown', u'Anonymous user', u"A person we don't know")

It implements zope.authentication.interfaces.IUnauthenticatedPrincipal:

>>> from zope.authentication import interfaces
>>> verifyObject(interfaces.IUnauthenticatedPrincipal, p)
True
>>> getValidationErrors(interfaces.IUnauthenticatedPrincipal, p)
[]

The unauthenticated principal will also be registered as a utility. This is to provide easy access to the data defined for the principal so that other (more featureful) principal objects can be created for the same principal.

>>> from zope import component
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> p.id, p.title, p.description
('zope.unknown', u'Anonymous user', u"A person we don't know")

The unauthenticated group

An unauthenticated group can also be defined in ZCML:

>>> zcml("""
...    <configure
...        xmlns="http://namespaces.zope.org/zope"
...        >
...
...      <unauthenticatedGroup
...         id="zope.unknowngroup"
...         title="Anonymous users"
...         description="People we don't know"
...         />
...
...    </configure>
... """)

This directive creates a group and registers it as a utility providing IUnauthenticatedGroup:

>>> g = component.getUtility(interfaces.IUnauthenticatedGroup)
>>> g.id, g.title, g.description
('zope.unknowngroup', u'Anonymous users', u"People we don't know")

It implements zope.authentication.interfaces.IUnauthenticatedGroup:

>>> verifyObject(interfaces.IUnauthenticatedGroup, g)
True
>>> getValidationErrors(interfaces.IUnauthenticatedGroup, g)
[]

The unauthenticatedGroup directive also updates the group of the unauthenticated principal:

>>> p = principalRegistry.unauthenticatedPrincipal()
>>> g.id in p.groups
True
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> g.id in p.groups
True

If the unauthenticated principal is defined after the unauthenticated group, it will likewise have the group added to it:

>>> reset()
>>> zcml("""
...    <configure xmlns="http://namespaces.zope.org/zope">
...
...      <unauthenticatedGroup
...         id="zope.unknowngroup2"
...         title="Anonymous users"
...         description="People we don't know"
...         />
...      <unauthenticatedPrincipal
...         id="zope.unknown2"
...         title="Anonymous user"
...         description="A person we don't know"
...         />
...
...    </configure>
... """)

>>> g = component.getUtility(interfaces.IUnauthenticatedGroup)
>>> g.id, g.title, g.description
('zope.unknowngroup2', u'Anonymous users', u"People we don't know")
>>> p = principalRegistry.unauthenticatedPrincipal()
>>> p.id, g.id in p.groups
('zope.unknown2', True)
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> p.id, g.id in p.groups
('zope.unknown2', True)

The unauthenticated group shows up as a principal in the principal registry:

>>> principalRegistry.getPrincipal(g.id) == g
True

>>> list(principalRegistry.getPrincipals("Anonymous")) == [g]
True

The authenticated group

There is an authenticated group:

>>> reset()
>>> zcml("""
...    <configure xmlns="http://namespaces.zope.org/zope">
...
...      <unauthenticatedPrincipal
...         id="zope.unknown3"
...         title="Anonymous user"
...         description="A person we don't know"
...         />
...      <principal
...         id="zope.manager2"
...         title="Manager"
...         description="System Manager"
...         login="admin"
...         password="123"
...         />
...      <authenticatedGroup
...         id="zope.authenticated"
...         title="Authenticated users"
...         description="People we know"
...         />
...      <principal
...         id="zope.manager3"
...         title="Manager 3"
...         login="admin3"
...         password="123"
...         />
...
...    </configure>
... """)

It defines an IAuthenticatedGroup utility:

>>> g = component.getUtility(interfaces.IAuthenticatedGroup)
>>> g.id, g.title, g.description
('zope.authenticated', u'Authenticated users', u'People we know')

It implements zope.authentication.interfaces.IUnauthenticatedGroup:

>>> verifyObject(interfaces.IAuthenticatedGroup, g)
True
>>> getValidationErrors(interfaces.IAuthenticatedGroup, g)
[]

It also adds it self to the groups of any non-group principals already defined, and, when non-group principals are defined, they put themselves in the group if it’s defined:

>>> principals = sorted(principalRegistry.getPrincipals(''),
...                     key=lambda p: p.id)
>>> for p in principals:
...    print(p.id, p.groups == [g.id])
zope.authenticated False
zope.manager2 True
zope.manager3 True

Excluding unauthenticated principals, of course:

>>> p = principalRegistry.unauthenticatedPrincipal()
>>> p.id, g.id in p.groups
('zope.unknown3', False)
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> p.id, g.id in p.groups
('zope.unknown3', False)

The everybody group

Finally, there is an everybody group:

>>> reset()
>>> zcml("""
...    <configure xmlns="http://namespaces.zope.org/zope">
...
...      <unauthenticatedPrincipal
...         id="zope.unknown4"
...         title="Anonymous user"
...         description="A person we don't know"
...         />
...      <principal
...         id="zope.manager4"
...         title="Manager"
...         description="System Manager"
...         login="admin"
...         password="123"
...         />
...      <everybodyGroup
...         id="zope.everybody"
...         title="Everybody"
...         description="All People"
...         />
...      <principal
...         id="zope.manager5"
...         title="Manager 5"
...         login="admin5"
...         password="123"
...         />
...
...    </configure>
... """)

The everybodyGroup directive defines an IEveryoneGroup utility:

>>> g = component.getUtility(interfaces.IEveryoneGroup)
>>> g.id, g.title, g.description
('zope.everybody', u'Everybody', u'All People')

It implements zope.authentication.interfaces.IEveryoneGroup:

>>> verifyObject(interfaces.IEveryoneGroup, g)
True
>>> getValidationErrors(interfaces.IEveryoneGroup, g)
[]

It also adds it self to the groups of any non-group principals already defined, and, when non-group principals are defined, they put themselves in the group if it’s defined:

>>> principals = sorted(principalRegistry.getPrincipals(''),
...                     key=lambda p: p.id)
>>> for p in principals:
...    print(p.id, p.groups == [g.id])
zope.everybody False
zope.manager4 True
zope.manager5 True

Including unauthenticated principals, of course:

>>> p = principalRegistry.unauthenticatedPrincipal()
>>> p.id, g.id in p.groups
('zope.unknown4', True)
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> p.id, g.id in p.groups
('zope.unknown4', True)

Note that it is up to IAuthentication implementations to associate these groups with their principals, as appropriate.

In our case, if we define an unauthenticated principal after having defined the everybody group, the principal will be automatically added:

>>> zcml("""
...    <configure xmlns="http://namespaces.zope.org/zope">
...
...      <unauthenticatedPrincipal
...         id="zope.unknown5"
...         title="Anonymous user"
...         description="A person we don't know"
...         />
...
...    </configure>
... """)
>>> p = component.getUtility(interfaces.IUnauthenticatedPrincipal)
>>> p.id, g.id in p.groups
('zope.unknown5', True)

The system_user

There is also a system_user that is defined in the code. It will be returned from the getPrincipal method of the registry.

>>> import zope.security.management
>>> import zope.principalregistry.principalregistry
>>> auth = zope.principalregistry.principalregistry.PrincipalRegistry()
>>> system_user = auth.getPrincipal(u'zope.security.management.system_user')
>>> system_user is zope.security.management.system_user
True

API Reference

Registry

Global Authentication Utility or Principal Registry

exception zope.principalregistry.principalregistry.DuplicateLogin

Bases: exceptions.Exception

exception zope.principalregistry.principalregistry.DuplicateId

Bases: exceptions.Exception

class zope.principalregistry.principalregistry.PrincipalRegistry

Bases: object

An in-memory implementation of zope.authentication.interfaces.IAuthentication and zope.authentication.interfaces.ILogout.

zope.principalregistry.principalregistry.principalRegistry = <zope.principalregistry.principalregistry.PrincipalRegistry object>

The global registry that the ZCML directives will modify.

class zope.principalregistry.principalregistry.Principal(id, title, description, login, pw, pwManagerName='Plain Text')

Bases: zope.principalregistry.principalregistry.PrincipalBase

The default implementation of zope.security.interfaces.IGroupAwarePrincipal that PrincipalRegistry will create.

class zope.principalregistry.principalregistry.UnauthenticatedPrincipal(id, title, description)

Bases: zope.principalregistry.principalregistry.PrincipalBase

An implementation of zope.authentication.interfaces.IUnauthenticatedPrincipal.

class zope.principalregistry.principalregistry.UnauthenticatedGroup(id, title, description)

Bases: zope.principalregistry.principalregistry.Group

An implementation of zope.authentication.interfaces.IUnauthenticatedGroup.

class zope.principalregistry.principalregistry.AuthenticatedGroup(id, title, description)

Bases: zope.principalregistry.principalregistry.Group

An implementation of zope.authentication.interfaces.IAuthenticatedGroup.

class zope.principalregistry.principalregistry.EverybodyGroup(id, title, description)

Bases: zope.principalregistry.principalregistry.Group

An implementation of zope.authentication.interfaces.IEverybodyGroup.

ZCML Directives

Schemas for directives that define principals and groups

class zope.principalregistry.metadirectives.TextId(min_length=0, max_length=None, **kw)

Bases: zope.schema._field.Id

An Id that is the text type instead of a native string.

This is required because IPrincipal defines id to be the text type.

interface zope.principalregistry.metadirectives.IBasePrincipalDirective

Base interface for principal definition directives.

id

Id

Id as which this object will be known and used.

Implementation:zope.principalregistry.metadirectives.TextId Read Only:False Required:True Default Value:None Allowed Type:unicode

title

Title

Provides a title for the object.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:unicode

description

Title

Provides a description for the object.

Implementation:zope.schema.TextLine Read Only:False Required:False Default Value:None Allowed Type:unicode

interface zope.principalregistry.metadirectives.IDefinePrincipalDirective

Extends: zope.principalregistry.metadirectives.IBasePrincipalDirective

Define a new principal.

login

Username/Login

Specifies the Principal’s Username/Login.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:unicode

password

Password

Specifies the Principal’s Password.

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:None Allowed Type:unicode

password_manager

Password Manager Name

Name of the password manager will be used for encode/check the password

Implementation:zope.schema.TextLine Read Only:False Required:True Default Value:u’Plain Text’ Allowed Type:unicode

interface zope.principalregistry.metadirectives.IDefineUnauthenticatedPrincipalDirective

Extends: zope.principalregistry.metadirectives.IBasePrincipalDirective

Define a new unauthenticated principal.

interface zope.principalregistry.metadirectives.IDefineUnauthenticatedGroupDirective

Extends: zope.principalregistry.metadirectives.IBasePrincipalDirective

Define the unauthenticated group.

interface zope.principalregistry.metadirectives.IDefineAuthenticatedGroupDirective

Extends: zope.principalregistry.metadirectives.IBasePrincipalDirective

Define the authenticated group.

interface zope.principalregistry.metadirectives.IDefineEverybodyGroupDirective

Extends: zope.principalregistry.metadirectives.IBasePrincipalDirective

Define the everybody group.

Directives for defining principals and groups

zope.principalregistry.metaconfigure.principal(_context, id, title, login, password, description='', password_manager='Plain Text')

Implementation of zope.principalregistry.metadirectives.IDefinePrincipalDirective.

zope.principalregistry.metaconfigure.unauthenticatedPrincipal(_context, id, title, description='')

Implementation of zope.principalregistry.metadirectives.IDefineUnauthenticatedPrincipalDirective.

zope.principalregistry.metaconfigure.unauthenticatedGroup(_context, id, title, description='')

Implementation of zope.principalregistry.metadirectives.IDefineUnauthenticatedGroupDirective.

zope.principalregistry.metaconfigure.authenticatedGroup(_context, id, title, description='')

Implementation of zope.principalregistry.metadirectives.IDefineAuthenticatedGroupDirective.

zope.principalregistry.metaconfigure.everybodyGroup(_context, id, title, description='')

Implementation of zope.principalregistry.metadirectives.IDefineEverybodyGroupDirective.

Changes

4.4 (unreleased)

• Add support for Python 3.11.

4.3 (2022-07-14)

• Drop support for Python 3.4.
• Add support for Python 3.7, 3.8, 3.9, 3.10.

4.2.0 (2017-10-01)

• Fix principal and group objects registered in ZCML or directly with the principalregistry being invalid under Python 2 (having byte strings for id instead of text strings). See https://github.com/zopefoundation/zope.principalregistry/issues/7

4.1.0 (2017-09-04)

• Add support for Python 3.5 and 3.6.
• Drop support for Python 2.6 and 3.3.
• Host documentation at https://zopeprincipalregistry.readthedocs.io
• Reach 100% test coverage and ensure we remain there.
• Test PyPy3 on Travis CI.

4.0.0 (2014-12-24)

• Add support for PyPy. (PyPy3 is pending release of a fix for: https://bitbucket.org/pypy/pypy/issue/1946)
• Add support for Python 3.4.
• Add support for testing under Travis.

4.0.0a2 (2013-03-03)

• Make sure that the password is always bytes when passed into the principal registry.
• Fix deprecation warnings.

4.0.0a1 (2013-02-22)

• Add support for Python 3.3.
• Replace deprecated zope.interface.implements usage with equivalent zope.interface.implementer decorator.
• Dropd support for Python 2.4 and 2.5.

3.7.1 (2010-09-25)

• Add test extra to declare test dependency on zope.component [test].
• Use Python’s doctest module instead of deprecated zope.testing.doctest.

3.7.0 (2009-03-14)

• Remove zope.container dependency, as contained principals didn’t make any sense, since PrincipalRegistry never provided IContainer. Also, zope.container pulls a number dependencies, that are not needed for non-persistent principal registry (like, ZCML, for example).

  Set __name__ and __parent__ by hand to provide some backward-compatibility and to save a pointer to registry from principal objects.

• Initial release. This package was split from zope.app.security as a part of the refactoring process to provide global principal registry without extra dependencies.

Development

zope.principalregistry is hosted at GitHub:

https://github.com/zopefoundation/zope.principalregistry/

Project URLs

• https://pypi.python.org/pypi/zope.principalregistry (PyPI entry and downloads)

Indices and tables

• Index
• Module Index
• Search Page