The default hash algorithm used in this policy is MD5 and has known
hash collision vulnerabilities. The risk of an exploit is low.
However, for improved authentication security, use
hashalg='sha512'.

Constructor Arguments

secret

The secret (a string) used for auth_tkt cookie signing. This value
should be unique across all values provided to Pyramid for various
subsystem secrets (see Admonishment Against Secret-Sharing).
Required.

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) if
the user does exist. If callback is None, 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.

For IPv6 this option is not recommended. The mod_auth_tkt
specification does not specify how to handle IPv6 addresses, so using
this option in combination with IPv6 addresses may cause an
incompatible cookie. It ties the authentication ticket to that
individual's IPv6 address.

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 is None, 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 is
0, 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 the
reissue_time value to perhaps a tenth of the timeout value
(120 or 2 mins). It's nonsensical to set the timeout value lower
than the reissue_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 from timeout inasmuch as timeout
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's Max-Age and
Expires 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 than timeout or
reissue_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. If your site is hosted as example.com this
will make the cookie available for sites underneath example.com
such as www.example.com.
Optional.

parent_domain

Default: False. An auth_tkt cookie will be generated for the
parent domain of the current site. For example if your site is
hosted under www.example.com a cookie will be generated for
.example.com. This can be useful if you have multiple sites
sharing the same domain. This option supercedes the wild_domain
option.
Optional.

This option is available as of Pyramid 1.5.

domain

Default: None. If provided the auth_tkt cookie will only be
set for this domain. This option is not compatible with wild_domain
and parent_domain.
Optional.

This option is available as of Pyramid 1.5.

hashalg

Default: md5 (the literal string).

Any hash algorithm supported by Python's hashlib.new() function
can be used as the hashalg.

Cookies generated by different instances of AuthTktAuthenticationPolicy
using different hashalg options are not compatible. Switching the
hashalg will imply that all existing users with a valid cookie will
be required to re-login.

A warning is emitted at startup if an explicit hashalg is not
passed. This is for backwards compatibility reasons.

This option is available as of Pyramid 1.4.

Optional.

Note

md5 is the default for backwards compatibility reasons. However,
if you don't specify md5 as the hashalg explicitly, a warning is
issued at application startup time. An explicit value of sha512
is recommended for improved security, and sha512 will become the
default in a future Pyramid version.

debug

Default: False. If debug is True, 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.

This will return a list of principals including, at least,
pyramid.security.Everyone. If there is no authenticated
userid, or the callback returns None, this will be the
only principal:

return[Everyone]

If the callback does not return None and an authenticated
userid is found, then the principals will include
pyramid.security.Authenticated, the authenticated_userid
and the list of principals returned by the callback:

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. If callback is None, the userid will be assumed
to exist with no group principals.

debug

Default: False. If debug is True, 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.

This will return a list of principals including, at least,
pyramid.security.Everyone. If there is no authenticated
userid, or the callback returns None, this will be the
only principal:

return[Everyone]

If the callback does not return None and an authenticated
userid is found, then the principals will include
pyramid.security.Authenticated, the authenticated_userid
and the list of principals returned by the callback:

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 return None if the userid doesn't
exist or a sequence of principal identifiers (possibly empty) if
the user does exist. If callback is None, the userid
will be assumed to exist with no principals. Optional.

debug

Default: False. If debug is True, 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.

This will return a list of principals including, at least,
pyramid.security.Everyone. If there is no authenticated
userid, or the callback returns None, this will be the
only principal:

return[Everyone]

If the callback does not return None and an authenticated
userid is found, then the principals will include
pyramid.security.Authenticated, the authenticated_userid
and the list of principals returned by the callback:

A Pyramid authentication policy which uses HTTP standard basic
authentication protocol to authenticate users. To use this policy you will
need to provide a callback which checks the supplied user credentials
against your source of login data.

Constructor Arguments

check

A callback function passed a username, password and request, in that
order as positional arguments. Expected to return None if the
userid doesn't exist or a sequence of principal identifiers (possibly
empty) if the user does exist.

realm

Default: "Realm". The Basic Auth Realm string. Usually displayed to
the user by the browser in the login dialog.

debug

Default: False. If debug is True, 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.

Issuing a challenge

Regular browsers will not send username/password credentials unless they
first receive a challenge from the server. The following recipe will
register a view that will send a Basic Auth challenge to the user whenever
there is an attempt to call a view which results in a Forbidden response:

This will return a list of principals including, at least,
pyramid.security.Everyone. If there is no authenticated
userid, or the callback returns None, this will be the
only principal:

return[Everyone]

If the callback does not return None and an authenticated
userid is found, then the principals will include
pyramid.security.Authenticated, the authenticated_userid
and the list of principals returned by the callback:

Default: auth_tkt. The repoze.who plugin name that
performs remember/forget. Optional.

callback

Default: None. A callback passed the repoze.who identity
and the request, expected to return None 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. If callback is None, the userid will be assumed to exist
with no group principals.

This will return a list of principals including, at least,
pyramid.security.Everyone. If there is no identity, or
the callback returns None, this will be the only principal.

If the callback does not return None and an identity is
found, then the principals will include
pyramid.security.Authenticated, the authenticated_userid
and the list of principals returned by the callback.

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.

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.

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 and Expires settings will be set,
allowing the auth_tkt cookie to last between browser sessions. If
this value is None, the max_age value provided to the
helper itself will be used as the max_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: ().