From 45fc3484387d5a917e4f749e9d0d8edc3119f2a8 Mon Sep 17 00:00:00 2001 From: Johannes Jarbratt <47516968+johachi@users.noreply.github.com> Date: Fri, 30 Apr 2021 06:31:20 +0900 Subject: [PATCH] Complete `jwt` documentation (#654) * Add warning and clarify how default values are set * Copy `jwt.decode` documentation to `jwt.decode_complete` * Customize `jwt.decode_complete` documentation --- docs/api.rst | 81 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 13 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 2b38b4a4..d23d4bdd 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -43,19 +43,23 @@ API Reference :param dict options: extended decoding and validation options - * ``require=[]`` list of claims that must be present. E.g. ``require=["exp", "iat", "nbf"]``. - Only verifies that the claims exists. Does NOT verify that the claims are valid. - * ``verify_aud=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``aud`` (audience) claim matches ``audience`` - * ``verify_iat=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``iat`` (issued at) claim value is an integer - * ``verify_exp=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``exp`` (expiration) claim value is OK - * ``verify_iss=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``iss`` (issuer) claim matches ``issuer`` - * ``verify_nbf=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``nbf`` (not before) is in the past * ``verify_signature=True`` verify the JWT cryptographic signature + * ``require=[]`` list of claims that must be present. + Example: ``require=["exp", "iat", "nbf"]``. + **Only verifies that the claims exists**. Does not verify that the claims are valid. + * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience`` + * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer`` + * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future + * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer + * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past + + .. warning:: + + ``exp``, ``iat`` and ``nbf`` will only be verified if present. + Please pass respective value to ``require`` if you want to make + sure that they are always present (and therefore always verified + if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively + is set to ``True``). :param Iterable audience: optional, the value for ``verify_aud`` check :param str issuer: optional, the value for ``verify_iss`` check @@ -63,7 +67,58 @@ API Reference :rtype: dict :returns: the JWT claims -.. note:: TODO: Document PyJWS / PyJWT classes +.. function:: decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0) + + Identical to ``jwt.decode`` except for return value which is a dictionary containing the token header (JOSE Header), + the token payload (JWT Payload), and token signature (JWT Signature) on the keys "header", "payload", + and "signature" respectively. + + :param str jwt: the token to be decoded + :param str key: the key suitable for the allowed algorithm + + :param list algorithms: allowed algorithms, e.g. ``["ES256"]`` + + .. warning:: + + Do **not** compute the ``algorithms`` parameter based on + the ``alg`` from the token itself, or on any other data + that an attacker may be able to influence, as that might + expose you to various vulnerabilities (see `RFC 8725 ยง2.1 + `_). Instead, + either hard-code a fixed value for ``algorithms``, or + configure it in the same place you configure the + ``key``. Make sure not to mix symmetric and asymmetric + algorithms that interpret the ``key`` in different ways + (e.g. HS\* and RS\*). + + :param dict options: extended decoding and validation options + + * ``verify_signature=True`` verify the JWT cryptographic signature + * ``require=[]`` list of claims that must be present. + Example: ``require=["exp", "iat", "nbf"]``. + **Only verifies that the claims exists**. Does not verify that the claims are valid. + * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience`` + * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer`` + * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future + * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer + * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past + + .. warning:: + + ``exp``, ``iat`` and ``nbf`` will only be verified if present. + Please pass respective value to ``require`` if you want to make + sure that they are always present (and therefore always verified + if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively + is set to ``True``). + + :param Iterable audience: optional, the value for ``verify_aud`` check + :param str issuer: optional, the value for ``verify_iss`` check + :param float leeway: a time margin in seconds for the expiration check + :rtype: dict + :returns: Decoded JWT with the JOSE Header on the key ``header``, the JWS + Payload on the key ``payload``, and the JWS Signature on the key ``signature``. + +.. note:: TODO: Document PyJWS class Exceptions ----------