pyramid.authentication
¶
Authentication Policies¶
-
class
AuthTktAuthenticationPolicy
(secret, callback=None, cookie_name='auth_tkt', secure=False, include_ip=False, timeout=None, reissue_time=None, max_age=None, path='/', http_only=False, wild_domain=True, debug=False)[source]¶ A Pyramid authentication policy which obtains data from a Pyramid “auth ticket” cookie.
Constructor Arguments
secret
The secret (a string) used for auth_tkt cookie signing. Required.callback
Default:None
. A callback passed the userid and the request, expected to returnNone
if the userid doesn’t exist or a sequence of principal identifiers (possibly empty) if the user does exist. Ifcallback
isNone
, the userid will be assumed to exist with no principals. Optional.cookie_name
Default:auth_tkt
. The cookie name used (string). Optional.secure
Default:False
. Only send the cookie back over a secure conn. Optional.include_ip
Default:False
. Make the requesting IP address part of the authentication data in the cookie. Optional.timeout
Default:None
. Maximum number of seconds which a newly issued ticket will be considered valid. After this amount of time, the ticket will expire (effectively logging the user out). If this value isNone
, the ticket never expires. Optional.reissue_time
Default:
None
. If this parameter is set, it represents the number of seconds that must pass before an authentication token cookie is automatically reissued as the result of a request which requires authentication. The duration is measured as the number of seconds since the last auth_tkt cookie was issued and ‘now’. If this value is0
, a new ticket cookie will be reissued on every request which requires authentication.A good rule of thumb: if you want auto-expired cookies based on inactivity: set the
timeout
value to 1200 (20 mins) and set thereissue_time
value to perhaps a tenth of thetimeout
value (120 or 2 mins). It’s nonsensical to set thetimeout
value lower than thereissue_time
value, as the ticket will never be reissued if so. However, such a configuration is not explicitly prevented.Optional.
max_age
Default:None
. The max age of the auth_tkt cookie, in seconds. This differs fromtimeout
inasmuch astimeout
represents the lifetime of the ticket contained in the cookie, while this value represents the lifetime of the cookie itself. When this value is set, the cookie’sMax-Age
andExpires
settings will be set, allowing the auth_tkt cookie to last between browser sessions. It is typically nonsensical to set this to a value that is lower thantimeout
orreissue_time
, although it is not explicitly prevented. Optional.path
Default:/
. The path for which the auth_tkt cookie is valid. May be desirable if the application only serves part of a domain. Optional.http_only
Default:False
. Hide cookie from JavaScript by setting the HttpOnly flag. Not honored by all browsers. Optional.wild_domain
Default:True
. An auth_tkt cookie will be generated for the wildcard domain. Optional.debug
Default:False
. Ifdebug
isTrue
, log messages to the Pyramid debug logger about the results of various authentication steps. The output from debugging is useful for reporting to maillist or IRC channels when asking for support.Objects of this class implement the interface described by
pyramid.interfaces.IAuthenticationPolicy
.
-
class
RepozeWho1AuthenticationPolicy
(identifier_name='auth_tkt', callback=None)[source]¶ A Pyramid authentication policy which obtains data from the
repoze.who
1.X WSGI ‘API’ (therepoze.who.identity
key in the WSGI environment).Constructor Arguments
identifier_name
Default:auth_tkt
. Therepoze.who
plugin name that performs remember/forget. Optional.callback
Default:None
. A callback passed therepoze.who
identity and the request, expected to returnNone
if the user represented by the identity doesn’t exist or a sequence of principal identifiers (possibly empty) representing groups if the user does exist. Ifcallback
is None, the userid will be assumed to exist with no group principals.Objects of this class implement the interface described by
pyramid.interfaces.IAuthenticationPolicy
.
-
class
RemoteUserAuthenticationPolicy
(environ_key='REMOTE_USER', callback=None, debug=False)[source]¶ A Pyramid authentication policy which obtains data from the
REMOTE_USER
WSGI environment variable.Constructor Arguments
environ_key
Default:REMOTE_USER
. The key in the WSGI environ which provides the userid.callback
Default:None
. A callback passed the userid and the request, expected to return None if the userid doesn’t exist or a sequence of principal identifiers (possibly empty) representing groups if the user does exist. Ifcallback
is None, the userid will be assumed to exist with no group principals.debug
Default:False
. Ifdebug
isTrue
, log messages to the Pyramid debug logger about the results of various authentication steps. The output from debugging is useful for reporting to maillist or IRC channels when asking for support.Objects of this class implement the interface described by
pyramid.interfaces.IAuthenticationPolicy
.
-
class
SessionAuthenticationPolicy
(prefix='auth.', callback=None, debug=False)[source]¶ A Pyramid authentication policy which gets its data from the configured session. For this authentication policy to work, you will have to follow the instructions in the Sessions to configure a session factory.
Constructor Arguments
prefix
A prefix used when storing the authentication parameters in the session. Defaults to ‘auth.’. Optional.callback
Default:None
. A callback passed the userid and the request, expected to returnNone
if the userid doesn’t exist or a sequence of principal identifiers (possibly empty) if the user does exist. Ifcallback
isNone
, the userid will be assumed to exist with no principals. Optional.debug
Default:False
. Ifdebug
isTrue
, log messages to the Pyramid debug logger about the results of various authentication steps. The output from debugging is useful for reporting to maillist or IRC channels when asking for support.
Helper Classes¶
- class
AuthTktCookieHelper
(secret, cookie_name='auth_tkt', secure=False, include_ip=False, timeout=None, reissue_time=None, max_age=None, http_only=False, path='/', wild_domain=True)[source]¶A helper class for use in third-party authentication policy implementations. See
pyramid.authentication.AuthTktAuthenticationPolicy
for the meanings of the constructor arguments.
- class
AuthTicket
(secret, userid, ip, tokens=(), user_data='', time=None, cookie_name='auth_tkt', secure=False)¶This class represents an authentication token. You must pass in the shared secret, the userid, and the IP address. Optionally you can include tokens (a list of strings, representing role names), ‘user_data’, which is arbitrary data available for your own use in later scripts. Lastly, you can override the cookie name and timestamp.
Once you provide all the arguments, use .cookie_value() to generate the appropriate authentication ticket.
Usage:
token = AuthTicket('sharedsecret', 'username', os.environ['REMOTE_ADDR'], tokens=['admin']) val = token.cookie_value()
- exception
AuthTktCookieHelper.
BadTicket
(msg, expected=None)¶Exception raised when a ticket can’t be parsed. If we get far enough to determine what the expected digest should have been, expected is set. This should not be shown by default, but can be useful for debugging.
AuthTktCookieHelper.
forget
(request)[source]¶Return a set of expires Set-Cookie headers, which will destroy any existing auth_tkt cookie when attached to a response
AuthTktCookieHelper.
identify
(request)[source]¶Return a dictionary with authentication information, or
None
if no valid auth_tkt is attached torequest
- static
AuthTktCookieHelper.
parse_ticket
(secret, ticket, ip)¶Parse the ticket, returning (timestamp, userid, tokens, user_data).
If the ticket cannot be parsed, a
BadTicket
exception will be raised with an explanation.
AuthTktCookieHelper.
remember
(request, userid, max_age=None, tokens=())[source]¶Return a set of Set-Cookie headers; when set into a response, these headers will represent a valid authentication ticket.
max_age
- The max age of the auth_tkt cookie, in seconds. When this value is set, the cookie’s
Max-Age
andExpires
settings will be set, allowing the auth_tkt cookie to last between browser sessions. If this value isNone
, themax_age
value provided to the helper itself will be used as themax_age
value. Default:None
.tokens
- A sequence of strings that will be placed into the auth_tkt tokens field. Each string in the sequence must be of the Python
str
type and must match the regex^[A-Za-z][A-Za-z0-9+_-]*$
. Tokens are available in the returned identity when an auth_tkt is found in the request and unpacked. Default:()
.