Skip to main content

Cryptographically signed query parameters for pyramid

Project description

Latest Version Supported Python versions License build status


This package provides a method for pyramid applications to sign parameters which are passed in query strings (or POST bodies).

The initial motivation for this was to be able to pass a return_url to a views without turning the app into open redirector.

Other use cases include being able to generate URLs (e.g. to be included in emails) which can be used to bypass the normal authentication/authorization mechanisms.


Pyramid-signed-params can be installed from PyPI using pip or easy_install (or buildout.) You should probably be installing it in a virtual environment.


You must configure at least one signing secret in your app settings. The secret should be a random, unguessable string. E.g. in your app’s .ini file:

pyramid_signed_params.secret = RGWO7nZ6W6AiPIUcXQN2iahJIThwH9BbpyZ7Lc1XfaOkPGt1GY


You can specify multiple signing keys (one per line.) If you do, the first key will be used for signing, while all keys will be tried when verifying signatures. This can be useful when rolling out a new signing key.

Activate the package by including it in your pyramid application.


This will add two new attributes to pyramid’s request.

  • request.sign_query(query, max_age=None, kid=None)

    Used to sign query arguments, e.g.

    # Pass the current URL as a signed *return_url* parameter to another view
    query = {'return_url': request.url}
    other_url = request.route_url('other', _query=request.sign_query(query))

    The max_age parameter can be used to generate signatures which expire after a certain amount of time.

    Passing kid="csrf" will create signatures which will be invalidated whenever the session’s CSRF token is changed.

  • request.signed_params

    This reified property will contain a multidict populated with all parameters passed to the request which were signed with a valid signature.

Basic Usage Example

Construct a URL which could be e-mailed out to allow changing the password of a given user:

# Construct a URL with some signed parameters
params = {'userid': 'fred', 'action': 'change-pw'}
signed_params = request.sign_query(params, max_age=3600)
url = request.route_url('change-pw', _query=signed_params)

Then, in the change-pw view:

if request.signed_params['action'] != 'change-pw':
    raise HTTPForbidden()
userid = request.signed_params['userid']

# Do whatever needs to be done to change the given users password

Note that because we passed max_age=3600 to sign_query, the URL will only work for an hour.


This package provides no inherent protection against replay attacks. If an attacker has access to a set of signed parameters, he may pass those signed parameters, unmodified, to any URL within the app (or other apps sharing the same signing secret.)


Jeff Dairiki


Next Release 0.1b5 (2018-03-08)

  • Use the new in PyJWT 1.6 more specific InvalidSignatureError in favor of the generic DecodeError to detect invalid signatures (when available.)


  • Test under both PyJWT 1.6 and 1.5.3.
  • Fix for changes in default log level in pytest 3.4.
  • As of pytest 3.3, pytest-catchlog has been rolled into the pytest core.

Release 0.1b4 (2017-12-18)


  • Drop CPython 3.3 classifier

Release 0.1b3 (2017-12-18)


  • Drop support for python 3.3.


  • Include LICENSE.txt and pytest.ini in sdist.

Release 0.1b2 (2017-11-16)

  • Change the signed_params reified request method so that it catches UnicodeDecodeErrors when accessing request.params, and returns an empty dict. (If the parameters are not properly encoded, there are no valid signed parameters.)

Release 0.1b1 (2017-11-16)

  • Drop support for python 2.6. Test under python 3.6.


  • Explicitly specify allowed algorithms when decoding JWTs.

Release 0.1a5 (2016-11-13)

  • Remove the (broken) config-time warning issued if no service is registered for ISignedParamsService. (When autocommit was off, this warning was always being issued.)

Release 0.1a4 (2016-11-02)

  • The setting for configuring the JWT signing secret(s) has been renamed to pyramid_signed_param.secret from pyramid_signed_param.secrets. Basic usage involve only a single secret. (Two allow for rotation of secrets, any configured secrets are accepted when verifying signatures, but only the first is used for creating new signatures.)
  • Pyramid_signed_params.include now issues a warning if the ISignedParamsService is not configured.
  • JWTSecretProviderFactory now raises a ConfigurationError if no secrets are found in the app settings.

Release 0.1a3 (2016-11-02)

Initial release.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pyramid_signed_params-0.1b5-py2.py3-none-any.whl (16.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3
pyramid-signed-params-0.1b5.tar.gz (11.8 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page