.. image:: https://github.com/morepath/more.jwtauth/workflows/CI/badge.svg?branch=master
:target: https://github.com/morepath/more.jwtauth/actions?workflow=CI
:alt: CI Status
.. image:: https://img.shields.io/pypi/v/more.jwtauth.svg
:target: https://pypi.org/project/more.jwtauth/
.. image:: https://img.shields.io/pypi/pyversions/more.jwtauth.svg
:target: https://pypi.org/project/more.jwtauth/
more.jwtauth: JWT Authentication integration for Morepath
=========================================================
Overview
--------
This is a Morepath_ authentication extension for the JSON Web Token (JWT)
Authentication.
For more information about JWT, see:
- `JSON Web Token draft`_ - the official JWT draft
- `Auth with JSON Web Tokens`_ - an interesting blog post by José Padilla
To access resources using JWT Access Authentication, the client must have
obtained a JWT to make signed requests to the server.
The Token can be opaque to client, although, unless it is encrypted,
the client can read the claims made in the token.
JWT validates the authenticity of the claimset using the signature.
This plugin uses the `PyJWT library`_ from José Padilla for verifying JWTs.
Introduction
------------
The general workflow of JWT Access Authentication:
* After the client has sent the login form we check if the user
exists and if the password is valid.
* In this case more.jwtauth generates a JWT token including all
information in a claim set and send it back to the client inside
the HTTP authentication header.
* The client stores it in some local storage and send it back in the
authentication header on every request.
* more.jwtauth validates the authenticity of the claim set using the
signature included in the token.
* The logout should be handled by the client by removing the token and
making some cleanup depending on the implementation.
You can include all necessary information about the identity in the token
so JWT Access Authentication can be used by a stateless service e.g. with
external password validation.
Requirements
------------
- Python (3.6, 3.7, 3.8, 3.9)
- morepath (>= 0.19)
- PyJWT (2.4.0)
- optional: cryptography (>= 3.3.2)
.. Note::
If you want to use another algorithm than HMAC (HS*), you need to install
cryptography.
On some systems this can be a little tricky. Please follow the instructions
in https://cryptography.io/en/latest/installation.
Installation
------------
You can use pip for installing more.jwtauth:
* ``pip install -U more.jwtauth[crypto]`` - for installing with cryptography
* ``pip install -U more.jwtauth`` - installing without cryptography
Usage
-----
For a basic setup just set the necessary settings including a key or key file
and pass them to JWTIdentityPolicy:
.. code-block:: python
import morepath
from more.jwtauth import JWTIdentityPolicy
class App(morepath.App):
pass
@App.setting_section(section="jwtauth")
def get_jwtauth_settings():
return {
# Set a key or key file.
'master_secret': 'secret',
# Adjust the settings which you need.
'leeway': 10
}
@App.identity_policy()
def get_identity_policy(settings):
# Get the jwtauth settings as a dictionary.
jwtauth_settings = settings.jwtauth.__dict__.copy()
# Pass the settings dictionary to the identity policy.
return JWTIdentityPolicy(**jwtauth_settings)
@App.verify_identity()
def verify_identity(identity):
# As we use a token based authentication
# we can trust the claimed identity.
return True
The login can be done in the standard Morepath way. You can add extra
information about the identity, which will be stored in the JWT token
and can be accessed through the morepath.Identity object:
.. code-block:: python
class Login:
pass
@App.path(model=Login, path='login')
def get_login():
return Login()
@App.view(model=Login, request_method='POST')
def login(self, request):
username = request.POST['username']
password = request.POST['password']
# Here you get some extra user information.
email = request.POST['email']
role = request.POST['role']
# Do the password validation.
if not user_has_password(username, password):
raise HTTPProxyAuthenticationRequired('Invalid username/password')
@request.after
def remember(response):
# We pass the extra info to the identity object.
identity = morepath.Identity(username, email=email, role=role)
request.app.remember_identity(response, request, identity)
return "You're logged in." # or something more fancy
Don't use reserved claim names as "iss", "aud", "exp", "nbf", "iat", "jti",
"refresh_until", "nonce" or the user_id_claim (default: "sub", see settings_).
They will be silently ignored.
Advanced:
For testing or if we want to use some methods of the JWTIdentityPolicy
class directly we can pass the settings as arguments to the class:
.. code-block:: python
identity_policy = JWTIdentityPolicy(
master_secret='secret',
leeway=10
)
Refreshing the token
--------------------
There are some risks related with using long-term tokens:
* If you use a stateless solution the token contains user data which
could not be up-to-date anymore.
* If a token get compromised there's no way to destroy sessions server-side.
A solution is to use short-term tokens and refresh them either just before
they expire or even after until the ``refresh_until`` claim not expires.
To help you with this more.jwtauth has a refresh API, which uses 4 settings:
* ``allow_refresh``: Enables the token refresh API when True.
Default is False
* ``refresh_delta``: The time delta in which the token can be refreshed
considering the leeway.
Default is 7 days. When None you can always refresh the token.
* ``refresh_nonce_handler``: Either dotted path to callback function or the
callback function itself, which receives the current request and the userid
as arguments and returns a nonce which will be validated before refreshing.
When None no nonce will be created or validated for refreshing.
* ``verify_expiration_on_refresh``: If False, expiration_delta for the JWT
token will not be checked during refresh. Otherwise you can refresh the
token only if it's not yet expired. Default is False.
When refreshing is enabled by setting ``refresh_delta`` the token can get
2 additional claims:
* ``refresh_until``: Timestamp until which the token can be refreshed.
* ``nonce``: The nonce which was generated by ``refresh_nonce_handler``.
So when you want to refresh your token, either because it has expires or
just before, you should adjust your jwtauth settings:
.. code-block:: python
@App.setting_section(section="jwtauth")
def get_jwtauth_settings():
return {
# Set a key or key file.
'master_secret': 'secret',
'allow_refresh': True,
'refresh_delta': 300,
'refresh_nonce_handler': 'yourapp.handler.refresh_nonce_handler'
}
Alternatively you can set the ``refresh_nonce_handler`` by decorating
a closure which returns the handler function:
.. code-block:: python
from .app import App
from .model import User
@App.setting(section="jwtauth", name="refresh_nonce_handler")
def get_handler():
def refresh_nonce_handler(request, userid):
# This returns a nonce from the user endity
# which can just be an UUID you created before.
return User.get(username=userid).nonce
return refresh_nonce_handler
After you can send a request to the refresh end-point for refreshing the token:
.. code-block:: python
from morepath import Identity
from more.jwtauth import (
verify_refresh_request, InvalidTokenError, ExpiredSignatureError
)
from .app import App
from .model import User
class Refresh:
pass
@App.path(model=Refresh, path='refresh')
def get_refresh():
return Refresh()
@App.view(model=Refresh)
def refresh(self, request):
try:
# Verifies if we're allowed to refresh the token.
# In this case returns the userid.
# If not raises exceptions based on InvalidTokenError.
# If expired this is a ExpiredSignatureError.
username = verify_refresh_request(request)
except ExpiredSignatureError:
@request.after
def expired_nonce_or_token(response):
response.status_code = 403
return "Your session has expired."
except InvalidTokenError:
@request.after
def invalid_token(response):
response.status_code = 403
return "Could not refresh your token."
else:
# get user info from the database to update the claims
User.get(username=username)
@request.after
def remember(response):
# create the identity with the userid and updated user info
identity = Identity(
username, email=user.email, role=user.role
)
# create the updated token and set it in the response header
request.app.remember_identity(response, request, identity)
return "Token sucessfully refreshed."
So now on every token refresh the user data gets updated.
When using the refresh_nonce_handler, you can just change the nonce
if the token gets compromised, e.g. by storing a new UUID in the user
endity, and the existing tokens will not be refreshed anymore.
Exceptions
~~~~~~~~~~
When refreshing the token fails, an exception is raised.
All exceptions are subclasses of ``more.jwtauth.InvalidTokenError``,
so you can catch them with ``except InvalidTokenError``.
For each exception a description of the failure is added.
The following exceptions could be raised:
* **InvalidTokenError**: A plain InvalidTokenError is used when the
refreshing API is disabled, the JWT token could not be found or
the refresh nonce is invalid.
* **ExpiredSignatureError**: when the ``refresh_until`` claim has expired
or when the JWT token has expired in case ``verify_expiration_on_refresh`` is enabled.
* **MissingRequiredClaimError**: When the ``refresh_until`` claim is
missing if a ``refresh_delta`` was provided or when the ``nonce``
claim is missing if ``refresh_nonce_handler`` is in use.
* **DecodeError**: When the JWT token could not be decoded.
Settings
--------
There are some settings that you can override. Here are all the defaults:
.. code-block:: python
@App.setting_section(section="jwtauth")
def get_jwtauth_settings():
return {
'master_secret': None,
'private_key': None,
'private_key_file': None,
'public_key': None,
'public_key_file': None,
'algorithm': "HS256",
'expiration_delta': datetime.timedelta(minutes=30),
'leeway': 0,
'allow_refresh': False,
'refresh_delta': timedelta(days=7),
'refresh_nonce_handler': None,
'verify_expiration_on_refresh': False,
'issuer': None,
'auth_header_prefix': "JWT",
'userid_claim': "sub"
}
The following settings are available:
master_secret
A secret known only by the server, used for the default HMAC (HS*) algorithm.
Default is None.
private_key
An Elliptic Curve or an RSA private_key used for the EC (EC*)
or RSA (PS*/RS*) algorithms. Default is None.
private_key_file
A file holding an Elliptic Curve or an RSA encoded (PEM/DER) private_key.
Default is None.
public_key
An Elliptic Curve or an RSA public_key used for the EC (EC*) or RSA (PS*/RS*)
algorithms. Default is None.
public_key_file
A file holding an Elliptic Curve or an RSA encoded (PEM/DER) public_key.
Default is None.
algorithm
The algorithm used to sign the key.
Defaults is HS256.
expiration_delta
Time delta from now until the token will expire. Set to None to disable.
This can either be a datetime.timedelta or the number of seconds.
Default is 30 minutes.
leeway
The leeway, which allows you to validate an expiration time which is in the
past, but not very far. To use either as a datetime.timedelta or the number
of seconds. Defaults is 0.
allow_refresh
Setting to True enables the refreshing API.
Default is False
refresh_delta
A time delta in which the token can be refreshed considering the leeway.
This can either be a datetime.timedelta or the number of seconds.
Default is 7 days. When None you can always refresh the token.
refresh_nonce_handler
Dotted path to callback function, which receives the userid as argument and
returns a nonce which will be validated before refreshing.
When None no nonce will be created or validated for refreshing.
Default is None.
verify_expiration_on_refresh
If False, expiration_delta for the JWT token will not be checked during
refresh. Otherwise you can refresh the token only if it's not yet expired.
Default is False.
issuer
This is a string that will be checked against the iss claim of the token.
You can use this e.g. if you have several related apps with exclusive user
audience. Default is None (do not check iss on JWT).
auth_header_prefix
You can modify the Authorization header value prefix that is required to be
sent together with the token. The default value is JWT.
Another common value used for tokens is Bearer.
userid_claim
The claim, which contains the user id.
The default claim is 'sub'.
The library takes either a master_secret or private_key/public_key pair.
In the later case the algorithm must be an EC*, PS* or RS* version.
Algorithms
----------
The JWT spec supports several algorithms for cryptographic signing.
This library currently supports:
HS256
HMAC using SHA-256 hash algorithm (default)
HS384
HMAC using SHA-384 hash algorithm
HS512
HMAC using SHA-512 hash algorithm
ES256 [1]_
ECDSA signature algorithm using SHA-256 hash algorithm
ES384 [1]_
ECDSA signature algorithm using SHA-384 hash algorithm
ES512 [1]_
ECDSA signature algorithm using SHA-512 hash algorithm
PS256 [1]_
RSASSA-PSS signature using SHA-256 and MGF1 padding with SHA-256
PS384 [1]_
RSASSA-PSS signature using SHA-384 and MGF1 padding with SHA-384
PS512 [1]_
RSASSA-PSS signature using SHA-512 and MGF1 padding with SHA-512
RS256 [1]_
RSASSA-PKCS1-v1_5 signature algorithm using SHA-256 hash algorithm
RS384 [1]_
RSASSA-PKCS1-v1_5 signature algorithm using SHA-384 hash algorithm
RS512 [1]_
RSASSA-PKCS1-v1_5 signature algorithm using SHA-512 hash algorithm
.. [1] The marked algorithms require more.jwtauth to be installed
with its ``crypto`` dependencies::
.. code-block:: console
pip install -U more.jwtauth[crypto]
See Installation_ for details. In case of problems be sure
to have read the note in the Requirements_ section.
Developing more.jwtauth
=======================
Install more.jwtauth for development
------------------------------------
Clone more.jwtauth from github::
.. code-block:: console
git clone git@github.com:morepath/more.jwtauth.git
If this doesn't work and you get an error 'Permission denied (publickey)',
you need to upload your ssh public key to github_.
Then go to the more.jwtauth directory::
.. code-block:: console
cd more.jwtauth
Make sure you have virtualenv_ installed.
Create a new virtualenv inside the more.jwtauth directory::
.. code-block:: console
python -m venv .venv
Activate the virtualenv::
.. code-block:: console
source .venv/bin/activate
Inside the virtualenv make sure you have recent setuptools and pip installed::
.. code-block:: console
pip install -U setuptools pip
Install the various dependencies and development tools from
develop_requirements.txt::
.. code-block:: console
pip install -Ur develop_requirements.txt
For upgrading the requirements just run the command again.
.. note::
The following commands work only if you have the virtualenv activated.
Install pre-commit hook for Black integration
---------------------------------------------
We're using Black_ for formatting the code and it's recommended to
install the `pre-commit hook`_ for Black integration before committing::
pre-commit install
.. _`pre-commit hook`: https://black.readthedocs.io/en/stable/version_control_integration.html
Running the tests
-----------------
You can run the tests using `pytest`_::
.. code-block:: console
pytest
To generate test coverage information as HTML do::
.. code-block:: console
pytest --cov --cov-report html
You can then point your web browser to the ``htmlcov/index.html`` file
in the project directory and click on modules to see detailed coverage
information.
.. _`pytest`: http://pytest.org/latest/
Black
-----
To format the code with the `Black Code Formatter`_ run in the root directory::
black .
Black has also `integration`_ for the most popular editors.
.. _`Black Code Formatter`: https://black.readthedocs.io
.. _`integration`: https://black.readthedocs.io/en/stable/editor_integration.html
Various checking tools
----------------------
flake8_ is a tool that can do various checks for common Python
mistakes using pyflakes_, check for PEP8_ style compliance and
can do `cyclomatic complexity`_ checking. To do pyflakes and pep8
checking do::
.. code-block:: console
flake8 more.jwtauth
To also show cyclomatic complexity, use this command::
.. code-block:: console
flake8 --max-complexity=10 more.jwtauth
Tox
---
With tox you can test Morepath under different Python environments.
We have Travis continuous integration installed on Morepath's github
repository and it runs the same tox tests after each checkin.
First you should install all Python versions which you want to
test. The versions which are not installed will be skipped. You should
at least install Python 3.7 which is required by flake8, coverage and
doctests.
One tool you can use to install multiple versions of Python is pyenv_.
To find out which test environments are defined for Morepath in tox.ini run::
.. code-block:: console
tox -l
You can run all tox tests with::
.. code-block:: console
tox
You can also specify a test environment to run e.g.::
.. code-block:: console
tox -e py37
tox -e pep8
tox -e coverage
.. _Morepath: http://morepath.readthedocs.org
.. _JSON Web Token draft:
http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html
.. _Auth with JSON Web Tokens:
http://jpadilla.com/post/73791304724/auth-with-json-web-tokens
.. _PyJWT library: http://github.com/progrium/pyjwt
.. _github: https://help.github.com/articles/generating-an-ssh-key
.. _virtualenv: https://pypi.python.org/pypi/virtualenv
.. _flake8: https://pypi.python.org/pypi/flake8
.. _pyflakes: https://pypi.python.org/pypi/pyflakes
.. _pep8: http://www.python.org/dev/peps/pep-0008/
.. _`cyclomatic complexity`:
https://en.wikipedia.org/wiki/Cyclomatic_complexity
.. _pyenv: https://github.com/yyuu/pyenv
CHANGES
=======
0.14 (2024-03-02)
-----------------
- Upgrade PyJWT and Cryptography dependencies.
- Fix test_refresh.
- **Removed**: Drop support for Python 3.6 and 3.7.
- Add support for Python 3.10, 3.11 and 3.12.
- Show full diffs in the test output.
- Update pre-commit revs.
- Adjust README.
0.13 (2022-06-19)
-----------------
- Remove obsolete decoding of encoded token.
- Upgrade PyJWT and Cryptography dependencies.
- Drop support for Python 3.5.
- Add support for Python 3.9.
- Use GitHub Actions for CI.
0.12 (2020-04-26)
-----------------
- **Removed**: Removed support for Python 2 and Python 3.4.
You have to upgrade to Python 3 if you want to use this version.
- Added support for Python 3.7 and 3.8 and PyPy 3.6.
- Make Python 3.7 the default testing environment.
- Upgrade PyJWT to version 1.7.1 and cryptography to version 2.9.2.
- Add integration for the Black code formatter.
0.11 (2018-01-18)
-----------------
- Remove support for Python 3.3 and add support for Python 3.6.
- Upgrade PyJWT to version 1.5.3 and cryptography to version 2.1.4.
0.10 (2017-12-08)
-----------------
- **Breaking:** Add request parameter to refresh_nonce_handler (see issue `#8`_).
.. _#8: https://github.com/morepath/more.jwtauth/issues/8
0.9 (2017-03-02)
----------------
- **New:** Add an API to refresh the JWT token (see issue `#6`_).
This implement adding 4 new settings:
* ``allow_refresh``: Enables the token refresh API when True.
* ``refresh_delta``: The time delta in which the token can be refreshed
considering the leeway.
* ``refresh_nonce_handler``: Dotted path to callback function, which receives
the userid as argument and returns a nonce which will be validated before
refreshing.
* ``verify_expiration_on_refresh``: If False, expiration_delta for the JWT
token will not be checked during refresh.
Otherwise you can refresh the token only if it's not yet expired.
It also adds 2 claims to the token when refreshing is enabled:
* ``refresh_until``: Timestamp until which the token can be refreshed.
* ``nonce``: The nonce which was returned by ``refresh_nonce_handler``.
For details see README.rst.
- **Removed:** The ``verify_expiration`` setting has been removed as it was
mainly for custom handling of token refreshing, which is now obsolete.
- Pass algorithm explicit to ``jwt.decode()`` to avoid some vulnerabilities.
For details see the blog post by Tim McLean about some
"`Critical vulnerabilities in JSON Web Token libraries`_".
- Allow expiration_delta and leeway as number of seconds in addition to
datetime.timedelta.
- Some code cleanup and refactoring.
.. _#6: https://github.com/morepath/more.jwtauth/issues/6
.. _Critical vulnerabilities in JSON Web Token libraries:
https://www.chosenplaintext.ca/2015/03/31/jwt-algorithm-confusion.html
0.8 (2016-10-21)
----------------
- We now use virtualenv and pip instead of buildout to set up the
development environment. A development section has been
added to the README accordingly.
- Review and optimize the tox configuration.
- Upgrade to PyJWT 1.4.2 and Cryptography 1.5.2.
0.7 (2016-07-20)
----------------
- Upgrade to Morepath 0.15.
- Upgrade to PyJWT 1.4.1 and Cryptography 1.4.
- Add testenv for Python 3.5 and make it the default test environment.
- Change author to "Morepath developers".
- Clean up classifiers.
0.6 (2016-05-19)
----------------
- Make Cryptography optional.
**Breaking Change:** For using other algorithms than HMAC you now need
to install the ``crypto`` dependencies explicitly. Read the note in the
Requirements section and the new Installation section of README.rst.
- Add an Installation section to the README.
- Refactor the cryptography test suite.
0.5 (2016-04-25)
----------------
- Adding some tests.
- Increase coverage to 100%.
- Add travis-ci and tox integration.
- Some clean-up.
- Upgrade to Morepath 0.14.
- Some improvements to the setup and release workflow.
0.4 (2016-04-13)
----------------
- Upgrade to Morepath 0.13.2 and update the tests.
- Upgrade PyJWT to 1.3.0 and cryptography to 1.3.1.
- Make it a PyPI package and release it. Fixes Issue #1.
0.3 (2016-04-13)
----------------
- Upgrade PyJWT to 1.4.0 and cryptography to 0.9.1.
- Python 3.2 is no longer a supported platform. This version of Python is rarely used.
PyUsers affected by this should upgrade to 3.3+.
- Some cleanup.
0.2 (2015-06-29)
----------------
- Integrate the set_jwt_auth_header function into the identity policy as remember method.
- Add support for PS256, PS384, and PS512 algorithms.
- Pass settings directly as arguments to the JWTIdentityPolicy class with the possibility
to override them with Morepath settings using the method introduced in Morepath 0.11.
- Remove JwtApp as now we use JWTIdentityPolicy directly without inherit from JwtApp.
- Add a Introduction and Usage section to README.
- Integrate all functions as methods in the JWTIdentityPolicy Class.
- Refactor the test suite.
0.1 (2015-04-15)
----------------
- Initial public release.
Raw data
{
"_id": null,
"home_page": "https://github.com/morepath/more.jwtauth",
"name": "more.jwtauth",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "morepath JWT identity authentication",
"author": "Morepath developers",
"author_email": "morepath@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/1c/98/b2aab9454ec3e02792d544008a97e42495a7dfb19c61a3780d446f52ba49/more.jwtauth-0.14.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/morepath/more.jwtauth/workflows/CI/badge.svg?branch=master\n :target: https://github.com/morepath/more.jwtauth/actions?workflow=CI\n :alt: CI Status\n\n.. image:: https://img.shields.io/pypi/v/more.jwtauth.svg\n :target: https://pypi.org/project/more.jwtauth/\n\n.. image:: https://img.shields.io/pypi/pyversions/more.jwtauth.svg\n :target: https://pypi.org/project/more.jwtauth/\n\n\nmore.jwtauth: JWT Authentication integration for Morepath\n=========================================================\n\nOverview\n--------\n\nThis is a Morepath_ authentication extension for the JSON Web Token (JWT)\nAuthentication.\n\nFor more information about JWT, see:\n\n- `JSON Web Token draft`_ - the official JWT draft\n- `Auth with JSON Web Tokens`_ - an interesting blog post by Jos\u00e9 Padilla\n\nTo access resources using JWT Access Authentication, the client must have\nobtained a JWT to make signed requests to the server.\nThe Token can be opaque to client, although, unless it is encrypted,\nthe client can read the claims made in the token.\n\nJWT validates the authenticity of the claimset using the signature.\n\nThis plugin uses the `PyJWT library`_ from Jos\u00e9 Padilla for verifying JWTs.\n\nIntroduction\n------------\n\nThe general workflow of JWT Access Authentication:\n * After the client has sent the login form we check if the user\n exists and if the password is valid.\n * In this case more.jwtauth generates a JWT token including all\n information in a claim set and send it back to the client inside\n the HTTP authentication header.\n * The client stores it in some local storage and send it back in the\n authentication header on every request.\n * more.jwtauth validates the authenticity of the claim set using the\n signature included in the token.\n * The logout should be handled by the client by removing the token and\n making some cleanup depending on the implementation.\n\nYou can include all necessary information about the identity in the token\nso JWT Access Authentication can be used by a stateless service e.g. with\nexternal password validation.\n\n\nRequirements\n------------\n\n- Python (3.6, 3.7, 3.8, 3.9)\n- morepath (>= 0.19)\n- PyJWT (2.4.0)\n- optional: cryptography (>= 3.3.2)\n\n.. Note::\n If you want to use another algorithm than HMAC (HS*), you need to install\n cryptography.\n On some systems this can be a little tricky. Please follow the instructions\n in https://cryptography.io/en/latest/installation.\n\n\nInstallation\n------------\n\nYou can use pip for installing more.jwtauth:\n\n* ``pip install -U more.jwtauth[crypto]`` - for installing with cryptography\n* ``pip install -U more.jwtauth`` - installing without cryptography\n\n\nUsage\n-----\n\nFor a basic setup just set the necessary settings including a key or key file\nand pass them to JWTIdentityPolicy:\n\n.. code-block:: python\n\n import morepath\n from more.jwtauth import JWTIdentityPolicy\n\n\n class App(morepath.App):\n pass\n\n\n @App.setting_section(section=\"jwtauth\")\n def get_jwtauth_settings():\n return {\n # Set a key or key file.\n 'master_secret': 'secret',\n\n # Adjust the settings which you need.\n 'leeway': 10\n }\n\n\n @App.identity_policy()\n def get_identity_policy(settings):\n # Get the jwtauth settings as a dictionary.\n jwtauth_settings = settings.jwtauth.__dict__.copy()\n\n # Pass the settings dictionary to the identity policy.\n return JWTIdentityPolicy(**jwtauth_settings)\n\n\n @App.verify_identity()\n def verify_identity(identity):\n # As we use a token based authentication\n # we can trust the claimed identity.\n return True\n\nThe login can be done in the standard Morepath way. You can add extra\ninformation about the identity, which will be stored in the JWT token\nand can be accessed through the morepath.Identity object:\n\n.. code-block:: python\n\n class Login:\n pass\n\n\n @App.path(model=Login, path='login')\n def get_login():\n return Login()\n\n\n @App.view(model=Login, request_method='POST')\n def login(self, request):\n username = request.POST['username']\n password = request.POST['password']\n\n # Here you get some extra user information.\n email = request.POST['email']\n role = request.POST['role']\n\n # Do the password validation.\n if not user_has_password(username, password):\n raise HTTPProxyAuthenticationRequired('Invalid username/password')\n\n @request.after\n def remember(response):\n # We pass the extra info to the identity object.\n identity = morepath.Identity(username, email=email, role=role)\n request.app.remember_identity(response, request, identity)\n\n return \"You're logged in.\" # or something more fancy\n\nDon't use reserved claim names as \"iss\", \"aud\", \"exp\", \"nbf\", \"iat\", \"jti\",\n\"refresh_until\", \"nonce\" or the user_id_claim (default: \"sub\", see settings_).\nThey will be silently ignored.\n\nAdvanced:\n For testing or if we want to use some methods of the JWTIdentityPolicy\n class directly we can pass the settings as arguments to the class:\n\n .. code-block:: python\n\n identity_policy = JWTIdentityPolicy(\n master_secret='secret',\n leeway=10\n )\n\n\nRefreshing the token\n--------------------\n\nThere are some risks related with using long-term tokens:\n\n* If you use a stateless solution the token contains user data which\n could not be up-to-date anymore.\n* If a token get compromised there's no way to destroy sessions server-side.\n\nA solution is to use short-term tokens and refresh them either just before\nthey expire or even after until the ``refresh_until`` claim not expires.\n\nTo help you with this more.jwtauth has a refresh API, which uses 4 settings:\n\n* ``allow_refresh``: Enables the token refresh API when True.\n Default is False\n* ``refresh_delta``: The time delta in which the token can be refreshed\n considering the leeway.\n Default is 7 days. When None you can always refresh the token.\n* ``refresh_nonce_handler``: Either dotted path to callback function or the\n callback function itself, which receives the current request and the userid\n as arguments and returns a nonce which will be validated before refreshing.\n When None no nonce will be created or validated for refreshing.\n* ``verify_expiration_on_refresh``: If False, expiration_delta for the JWT\n token will not be checked during refresh. Otherwise you can refresh the\n token only if it's not yet expired. Default is False.\n\nWhen refreshing is enabled by setting ``refresh_delta`` the token can get\n2 additional claims:\n\n* ``refresh_until``: Timestamp until which the token can be refreshed.\n* ``nonce``: The nonce which was generated by ``refresh_nonce_handler``.\n\nSo when you want to refresh your token, either because it has expires or\njust before, you should adjust your jwtauth settings:\n\n.. code-block:: python\n\n @App.setting_section(section=\"jwtauth\")\n def get_jwtauth_settings():\n return {\n # Set a key or key file.\n 'master_secret': 'secret',\n 'allow_refresh': True,\n 'refresh_delta': 300,\n 'refresh_nonce_handler': 'yourapp.handler.refresh_nonce_handler'\n }\n\nAlternatively you can set the ``refresh_nonce_handler`` by decorating\na closure which returns the handler function:\n\n.. code-block:: python\n\n from .app import App\n from .model import User\n\n\n @App.setting(section=\"jwtauth\", name=\"refresh_nonce_handler\")\n def get_handler():\n def refresh_nonce_handler(request, userid):\n # This returns a nonce from the user endity\n # which can just be an UUID you created before.\n return User.get(username=userid).nonce\n return refresh_nonce_handler\n\nAfter you can send a request to the refresh end-point for refreshing the token:\n\n.. code-block:: python\n\n from morepath import Identity\n from more.jwtauth import (\n verify_refresh_request, InvalidTokenError, ExpiredSignatureError\n )\n\n from .app import App\n from .model import User\n\n\n class Refresh:\n pass\n\n\n @App.path(model=Refresh, path='refresh')\n def get_refresh():\n return Refresh()\n\n\n @App.view(model=Refresh)\n def refresh(self, request):\n try:\n # Verifies if we're allowed to refresh the token.\n # In this case returns the userid.\n # If not raises exceptions based on InvalidTokenError.\n # If expired this is a ExpiredSignatureError.\n username = verify_refresh_request(request)\n except ExpiredSignatureError:\n @request.after\n def expired_nonce_or_token(response):\n response.status_code = 403\n return \"Your session has expired.\"\n except InvalidTokenError:\n @request.after\n def invalid_token(response):\n response.status_code = 403\n return \"Could not refresh your token.\"\n else:\n # get user info from the database to update the claims\n User.get(username=username)\n\n @request.after\n def remember(response):\n # create the identity with the userid and updated user info\n identity = Identity(\n username, email=user.email, role=user.role\n )\n # create the updated token and set it in the response header\n request.app.remember_identity(response, request, identity)\n\n return \"Token sucessfully refreshed.\"\n\nSo now on every token refresh the user data gets updated.\n\nWhen using the refresh_nonce_handler, you can just change the nonce\nif the token gets compromised, e.g. by storing a new UUID in the user\nendity, and the existing tokens will not be refreshed anymore.\n\nExceptions\n~~~~~~~~~~\n\nWhen refreshing the token fails, an exception is raised.\nAll exceptions are subclasses of ``more.jwtauth.InvalidTokenError``,\nso you can catch them with ``except InvalidTokenError``.\nFor each exception a description of the failure is added.\nThe following exceptions could be raised:\n\n* **InvalidTokenError**: A plain InvalidTokenError is used when the\n refreshing API is disabled, the JWT token could not be found or\n the refresh nonce is invalid.\n* **ExpiredSignatureError**: when the ``refresh_until`` claim has expired\n or when the JWT token has expired in case ``verify_expiration_on_refresh`` is enabled.\n* **MissingRequiredClaimError**: When the ``refresh_until`` claim is\n missing if a ``refresh_delta`` was provided or when the ``nonce``\n claim is missing if ``refresh_nonce_handler`` is in use.\n* **DecodeError**: When the JWT token could not be decoded.\n\n\nSettings\n--------\n\nThere are some settings that you can override. Here are all the defaults:\n\n.. code-block:: python\n\n @App.setting_section(section=\"jwtauth\")\n def get_jwtauth_settings():\n return {\n 'master_secret': None,\n 'private_key': None,\n 'private_key_file': None,\n 'public_key': None,\n 'public_key_file': None,\n 'algorithm': \"HS256\",\n 'expiration_delta': datetime.timedelta(minutes=30),\n 'leeway': 0,\n 'allow_refresh': False,\n 'refresh_delta': timedelta(days=7),\n 'refresh_nonce_handler': None,\n 'verify_expiration_on_refresh': False,\n 'issuer': None,\n 'auth_header_prefix': \"JWT\",\n 'userid_claim': \"sub\"\n }\n\nThe following settings are available:\n\nmaster_secret\n A secret known only by the server, used for the default HMAC (HS*) algorithm.\n Default is None.\n\nprivate_key\n An Elliptic Curve or an RSA private_key used for the EC (EC*)\n or RSA (PS*/RS*) algorithms. Default is None.\n\nprivate_key_file\n A file holding an Elliptic Curve or an RSA encoded (PEM/DER) private_key.\n Default is None.\n\npublic_key\n An Elliptic Curve or an RSA public_key used for the EC (EC*) or RSA (PS*/RS*)\n algorithms. Default is None.\n\npublic_key_file\n A file holding an Elliptic Curve or an RSA encoded (PEM/DER) public_key.\n Default is None.\n\nalgorithm\n The algorithm used to sign the key.\n Defaults is HS256.\n\nexpiration_delta\n Time delta from now until the token will expire. Set to None to disable.\n This can either be a datetime.timedelta or the number of seconds.\n Default is 30 minutes.\n\nleeway\n The leeway, which allows you to validate an expiration time which is in the\n past, but not very far. To use either as a datetime.timedelta or the number\n of seconds. Defaults is 0.\n\nallow_refresh\n Setting to True enables the refreshing API.\n Default is False\n\nrefresh_delta\n A time delta in which the token can be refreshed considering the leeway.\n This can either be a datetime.timedelta or the number of seconds.\n Default is 7 days. When None you can always refresh the token.\n\nrefresh_nonce_handler\n Dotted path to callback function, which receives the userid as argument and\n returns a nonce which will be validated before refreshing.\n When None no nonce will be created or validated for refreshing.\n Default is None.\n\nverify_expiration_on_refresh\n If False, expiration_delta for the JWT token will not be checked during\n refresh. Otherwise you can refresh the token only if it's not yet expired.\n Default is False.\n\nissuer\n This is a string that will be checked against the iss claim of the token.\n You can use this e.g. if you have several related apps with exclusive user\n audience. Default is None (do not check iss on JWT).\n\nauth_header_prefix\n You can modify the Authorization header value prefix that is required to be\n sent together with the token. The default value is JWT.\n Another common value used for tokens is Bearer.\n\nuserid_claim\n The claim, which contains the user id.\n The default claim is 'sub'.\n\nThe library takes either a master_secret or private_key/public_key pair.\nIn the later case the algorithm must be an EC*, PS* or RS* version.\n\n\nAlgorithms\n----------\n\nThe JWT spec supports several algorithms for cryptographic signing.\nThis library currently supports:\n\nHS256\n HMAC using SHA-256 hash algorithm (default)\n\nHS384\n HMAC using SHA-384 hash algorithm\n\nHS512\n HMAC using SHA-512 hash algorithm\n\nES256 [1]_\n ECDSA signature algorithm using SHA-256 hash algorithm\n\nES384 [1]_\n ECDSA signature algorithm using SHA-384 hash algorithm\n\nES512 [1]_\n ECDSA signature algorithm using SHA-512 hash algorithm\n\nPS256 [1]_\n RSASSA-PSS signature using SHA-256 and MGF1 padding with SHA-256\n\nPS384 [1]_\n RSASSA-PSS signature using SHA-384 and MGF1 padding with SHA-384\n\nPS512 [1]_\n RSASSA-PSS signature using SHA-512 and MGF1 padding with SHA-512\n\nRS256 [1]_\n RSASSA-PKCS1-v1_5 signature algorithm using SHA-256 hash algorithm\n\nRS384 [1]_\n RSASSA-PKCS1-v1_5 signature algorithm using SHA-384 hash algorithm\n\nRS512 [1]_\n RSASSA-PKCS1-v1_5 signature algorithm using SHA-512 hash algorithm\n\n.. [1] The marked algorithms require more.jwtauth to be installed\n with its ``crypto`` dependencies::\n\n .. code-block:: console\n\n pip install -U more.jwtauth[crypto]\n\n See Installation_ for details. In case of problems be sure\n to have read the note in the Requirements_ section.\n\n\nDeveloping more.jwtauth\n=======================\n\nInstall more.jwtauth for development\n------------------------------------\n\nClone more.jwtauth from github::\n\n.. code-block:: console\n\n git clone git@github.com:morepath/more.jwtauth.git\n\nIf this doesn't work and you get an error 'Permission denied (publickey)',\nyou need to upload your ssh public key to github_.\n\nThen go to the more.jwtauth directory::\n\n.. code-block:: console\n\n cd more.jwtauth\n\nMake sure you have virtualenv_ installed.\n\nCreate a new virtualenv inside the more.jwtauth directory::\n\n.. code-block:: console\n\n python -m venv .venv\n\nActivate the virtualenv::\n\n.. code-block:: console\n\n source .venv/bin/activate\n\nInside the virtualenv make sure you have recent setuptools and pip installed::\n\n.. code-block:: console\n\n pip install -U setuptools pip\n\nInstall the various dependencies and development tools from\ndevelop_requirements.txt::\n\n.. code-block:: console\n\n pip install -Ur develop_requirements.txt\n\nFor upgrading the requirements just run the command again.\n\n.. note::\n\n The following commands work only if you have the virtualenv activated.\n\nInstall pre-commit hook for Black integration\n---------------------------------------------\n\nWe're using Black_ for formatting the code and it's recommended to\ninstall the `pre-commit hook`_ for Black integration before committing::\n\n pre-commit install\n\n.. _`pre-commit hook`: https://black.readthedocs.io/en/stable/version_control_integration.html\n\nRunning the tests\n-----------------\n\nYou can run the tests using `pytest`_::\n\n.. code-block:: console\n\n pytest\n\nTo generate test coverage information as HTML do::\n\n.. code-block:: console\n\n pytest --cov --cov-report html\n\nYou can then point your web browser to the ``htmlcov/index.html`` file\nin the project directory and click on modules to see detailed coverage\ninformation.\n\n.. _`pytest`: http://pytest.org/latest/\n\nBlack\n-----\n\nTo format the code with the `Black Code Formatter`_ run in the root directory::\n\n black .\n\nBlack has also `integration`_ for the most popular editors.\n\n.. _`Black Code Formatter`: https://black.readthedocs.io\n.. _`integration`: https://black.readthedocs.io/en/stable/editor_integration.html\n\nVarious checking tools\n----------------------\n\nflake8_ is a tool that can do various checks for common Python\nmistakes using pyflakes_, check for PEP8_ style compliance and\ncan do `cyclomatic complexity`_ checking. To do pyflakes and pep8\nchecking do::\n\n.. code-block:: console\n\n flake8 more.jwtauth\n\nTo also show cyclomatic complexity, use this command::\n\n.. code-block:: console\n\n flake8 --max-complexity=10 more.jwtauth\n\nTox\n---\n\nWith tox you can test Morepath under different Python environments.\n\nWe have Travis continuous integration installed on Morepath's github\nrepository and it runs the same tox tests after each checkin.\n\nFirst you should install all Python versions which you want to\ntest. The versions which are not installed will be skipped. You should\nat least install Python 3.7 which is required by flake8, coverage and\ndoctests.\n\nOne tool you can use to install multiple versions of Python is pyenv_.\n\nTo find out which test environments are defined for Morepath in tox.ini run::\n\n.. code-block:: console\n\n tox -l\n\nYou can run all tox tests with::\n\n.. code-block:: console\n\n tox\n\nYou can also specify a test environment to run e.g.::\n\n.. code-block:: console\n\n tox -e py37\n tox -e pep8\n tox -e coverage\n\n\n.. _Morepath: http://morepath.readthedocs.org\n.. _JSON Web Token draft:\n http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html\n.. _Auth with JSON Web Tokens:\n http://jpadilla.com/post/73791304724/auth-with-json-web-tokens\n.. _PyJWT library: http://github.com/progrium/pyjwt\n.. _github: https://help.github.com/articles/generating-an-ssh-key\n.. _virtualenv: https://pypi.python.org/pypi/virtualenv\n.. _flake8: https://pypi.python.org/pypi/flake8\n.. _pyflakes: https://pypi.python.org/pypi/pyflakes\n.. _pep8: http://www.python.org/dev/peps/pep-0008/\n.. _`cyclomatic complexity`:\n https://en.wikipedia.org/wiki/Cyclomatic_complexity\n.. _pyenv: https://github.com/yyuu/pyenv\n\n\nCHANGES\n=======\n\n0.14 (2024-03-02)\n-----------------\n\n- Upgrade PyJWT and Cryptography dependencies.\n\n- Fix test_refresh.\n\n- **Removed**: Drop support for Python 3.6 and 3.7.\n\n- Add support for Python 3.10, 3.11 and 3.12.\n\n- Show full diffs in the test output.\n\n- Update pre-commit revs.\n\n- Adjust README.\n\n\n0.13 (2022-06-19)\n-----------------\n\n- Remove obsolete decoding of encoded token.\n\n- Upgrade PyJWT and Cryptography dependencies.\n\n- Drop support for Python 3.5.\n\n- Add support for Python 3.9.\n\n- Use GitHub Actions for CI.\n\n\n0.12 (2020-04-26)\n-----------------\n\n- **Removed**: Removed support for Python 2 and Python 3.4.\n \n You have to upgrade to Python 3 if you want to use this version.\n\n- Added support for Python 3.7 and 3.8 and PyPy 3.6.\n\n- Make Python 3.7 the default testing environment.\n\n- Upgrade PyJWT to version 1.7.1 and cryptography to version 2.9.2.\n\n- Add integration for the Black code formatter.\n\n\n0.11 (2018-01-18)\n-----------------\n\n- Remove support for Python 3.3 and add support for Python 3.6.\n- Upgrade PyJWT to version 1.5.3 and cryptography to version 2.1.4.\n\n\n0.10 (2017-12-08)\n-----------------\n\n- **Breaking:** Add request parameter to refresh_nonce_handler (see issue `#8`_).\n\n.. _#8: https://github.com/morepath/more.jwtauth/issues/8\n\n\n0.9 (2017-03-02)\n----------------\n\n- **New:** Add an API to refresh the JWT token (see issue `#6`_).\n\n This implement adding 4 new settings:\n\n * ``allow_refresh``: Enables the token refresh API when True.\n * ``refresh_delta``: The time delta in which the token can be refreshed\n considering the leeway.\n * ``refresh_nonce_handler``: Dotted path to callback function, which receives\n the userid as argument and returns a nonce which will be validated before\n refreshing.\n * ``verify_expiration_on_refresh``: If False, expiration_delta for the JWT\n token will not be checked during refresh.\n Otherwise you can refresh the token only if it's not yet expired.\n\n It also adds 2 claims to the token when refreshing is enabled:\n\n * ``refresh_until``: Timestamp until which the token can be refreshed.\n * ``nonce``: The nonce which was returned by ``refresh_nonce_handler``.\n\n For details see README.rst.\n\n- **Removed:** The ``verify_expiration`` setting has been removed as it was\n mainly for custom handling of token refreshing, which is now obsolete.\n\n- Pass algorithm explicit to ``jwt.decode()`` to avoid some vulnerabilities.\n For details see the blog post by Tim McLean about some\n \"`Critical vulnerabilities in JSON Web Token libraries`_\".\n\n- Allow expiration_delta and leeway as number of seconds in addition to\n datetime.timedelta.\n\n- Some code cleanup and refactoring.\n\n.. _#6: https://github.com/morepath/more.jwtauth/issues/6\n.. _Critical vulnerabilities in JSON Web Token libraries:\n https://www.chosenplaintext.ca/2015/03/31/jwt-algorithm-confusion.html\n\n\n0.8 (2016-10-21)\n----------------\n\n- We now use virtualenv and pip instead of buildout to set up the\n development environment. A development section has been\n added to the README accordingly.\n- Review and optimize the tox configuration.\n- Upgrade to PyJWT 1.4.2 and Cryptography 1.5.2.\n\n\n0.7 (2016-07-20)\n----------------\n\n- Upgrade to Morepath 0.15.\n- Upgrade to PyJWT 1.4.1 and Cryptography 1.4.\n- Add testenv for Python 3.5 and make it the default test environment.\n- Change author to \"Morepath developers\".\n- Clean up classifiers.\n\n\n0.6 (2016-05-19)\n----------------\n\n- Make Cryptography optional.\n\n **Breaking Change:** For using other algorithms than HMAC you now need\n to install the ``crypto`` dependencies explicitly. Read the note in the\n Requirements section and the new Installation section of README.rst.\n\n- Add an Installation section to the README.\n- Refactor the cryptography test suite.\n\n\n0.5 (2016-04-25)\n----------------\n\n- Adding some tests.\n- Increase coverage to 100%.\n- Add travis-ci and tox integration.\n- Some clean-up.\n- Upgrade to Morepath 0.14.\n- Some improvements to the setup and release workflow.\n\n\n\n0.4 (2016-04-13)\n----------------\n\n- Upgrade to Morepath 0.13.2 and update the tests.\n- Upgrade PyJWT to 1.3.0 and cryptography to 1.3.1.\n- Make it a PyPI package and release it. Fixes Issue #1.\n\n\n0.3 (2016-04-13)\n----------------\n\n- Upgrade PyJWT to 1.4.0 and cryptography to 0.9.1.\n- Python 3.2 is no longer a supported platform. This version of Python is rarely used.\n PyUsers affected by this should upgrade to 3.3+.\n- Some cleanup.\n\n0.2 (2015-06-29)\n----------------\n\n- Integrate the set_jwt_auth_header function into the identity policy as remember method.\n\n- Add support for PS256, PS384, and PS512 algorithms.\n\n- Pass settings directly as arguments to the JWTIdentityPolicy class with the possibility\n to override them with Morepath settings using the method introduced in Morepath 0.11.\n\n- Remove JwtApp as now we use JWTIdentityPolicy directly without inherit from JwtApp.\n\n- Add a Introduction and Usage section to README.\n\n- Integrate all functions as methods in the JWTIdentityPolicy Class.\n\n- Refactor the test suite.\n\n\n0.1 (2015-04-15)\n----------------\n\n- Initial public release.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "JWT Access Auth Identity Policy for Morepath",
"version": "0.14",
"project_urls": {
"Homepage": "https://github.com/morepath/more.jwtauth"
},
"split_keywords": [
"morepath",
"jwt",
"identity",
"authentication"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "db7fc39ca7f736f329bc7c7aa0713e58f8fa8d19859da7dcd1507b82e17ba49f",
"md5": "747e5682770ea933552cb7e83428354f",
"sha256": "f3b1a61aad9fb98dd0a5584d556c49a69246a27fac45c2bd67cceda6eba3ed6a"
},
"downloads": -1,
"filename": "more.jwtauth-0.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "747e5682770ea933552cb7e83428354f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25113,
"upload_time": "2024-03-03T01:02:35",
"upload_time_iso_8601": "2024-03-03T01:02:35.946852Z",
"url": "https://files.pythonhosted.org/packages/db/7f/c39ca7f736f329bc7c7aa0713e58f8fa8d19859da7dcd1507b82e17ba49f/more.jwtauth-0.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c98b2aab9454ec3e02792d544008a97e42495a7dfb19c61a3780d446f52ba49",
"md5": "b35f346a7a375a5ea9ebd6cc7bd4126c",
"sha256": "58e76e0faf9c4796cb378f46f7c12e76e403a50654541e7f1b15b7b929eb5aa0"
},
"downloads": -1,
"filename": "more.jwtauth-0.14.tar.gz",
"has_sig": false,
"md5_digest": "b35f346a7a375a5ea9ebd6cc7bd4126c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31990,
"upload_time": "2024-03-03T01:02:38",
"upload_time_iso_8601": "2024-03-03T01:02:38.219989Z",
"url": "https://files.pythonhosted.org/packages/1c/98/b2aab9454ec3e02792d544008a97e42495a7dfb19c61a3780d446f52ba49/more.jwtauth-0.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-03 01:02:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "morepath",
"github_project": "more.jwtauth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "more.jwtauth"
}
JSON
