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.
There are no attributes or fields specified.
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.
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, ILoginPassword, place=self)
The place 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 be an 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.