pyramid AuthTktAuthenticationPolicy secret parameter

Question

What exactly is the 'secret' parameter of Pyramid's pyramid.authentication.AuthTktAuthenticationPolicy function? The documentation says that it's "(a string) used for auth_tkt cookie signing. Required." The tutorial says that it's "is a string representing an encryption key used by the 'authentication ticket' machinery represented by this policy".

What is auth_tkt cookie signing? What is this 'authentication ticket' machinery? Is this secret supposed to be something I store as a hash in a database or something? I'm really confused.

Answer 1

A tkt auth cookie is a secure hash of several pieces of information, including the username and optionally a timestamp, but not the user password. Once authenticated, you give such a cookie to the user, and every time the user returns you just extract the username again and know it's the same user.

To keep this cookie secure, you need to have a server-side secret, however. Only a server in possession of that secret can create these cookies; if an attacker ever got hold of it he could generate authentication cookies for arbitrary users without ever needing to know the passwords of these users.

The secret parameter for the policy is that server-side secret; it's like a master password for your server. If you run more than one process for your site (and with WSGI, you usually do), you need to make it consistent across your processes, to make sure each process can verify the cookies. You can specify it in your configuration file, in your source code, or in your database; it depends on how much flexibility you need, your security policies, and whether or not you need to share the secret with other systems.

You can share the secret with other systems in your domain that also need to authenticate your users, using the same standard. Apache has a mod_auth_tkt module for example, Plone uses the same standard, and by sharing the secret you can provide a single sign-on for your users across disparate web applications.

Note that changing the secret means existing sessions become invalid, and users would have to re-authenticate.

In any case, existing cookies can have a limited life-span; the embedded timestamp limits how long it will be accepted as valid, if you configure the timeout parameter on the policy. It's good policy to set a timeout, combined with a reissue time; any user that re-visits your application within the timeout will be re-issued a new cookie with a new timestamp to keep their session fresh. That way your session cookies automatically expire if your users do not return, and their cookie cannot be reused by an attacker at a later time. The reissue parameter lets you control how quickly a new token is issued; revisit your server within reissue seconds would not produce a new token.

Answer 2

The secret parameter as far as I remember is just a string used as a salt for the creation of the cookie. You can put whatever you want. Having it in your config file should be more than enough. Saving it in the database might be overkill though if you want to invalidate anything created, I guess changing the secret will invalidate all cookies and session create before that change.