From b15de0b4f1489c4c38f40cdf3d3cd8ec5094948e Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Mon, 4 Aug 2025 15:56:17 +0200 Subject: [PATCH 1/3] IS-18431: Expand decode_jwt docs and reorganize Jinja filters page --- hub/changelog.rst | 7 ++ hub/documentation/jinja_filters.rst | 141 +++++++++++++++++++++++----- 2 files changed, 125 insertions(+), 23 deletions(-) diff --git a/hub/changelog.rst b/hub/changelog.rst index 5ccdb34ce3..bb3c8bf376 100644 --- a/hub/changelog.rst +++ b/hub/changelog.rst @@ -1,6 +1,13 @@ Changelog ========= +.. _changelog_2025-08-04: + +2025-08-04 +---------- +* The ``decode_jwt`` Jinja :ref:`filter ` now supports a new argument ``jwks_url``. This can be used to obtain keys dynamically + from a JSON Web Key Set (JWKS) URL, instead of specifying it under the ``key`` argument. + .. _changelog_2025-07-01: 2025-07-01 diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst index 5a04bec868..58086eb6a6 100644 --- a/hub/documentation/jinja_filters.rst +++ b/hub/documentation/jinja_filters.rst @@ -6,51 +6,146 @@ Jinja filters ============= In addition to the `built-in filters `_, -we have also defined custom Jinja filters that can be used in pipe and system configurations. Most of these filters -have a corresponding DTL function and should produce the same output, e.g. the ``bytes`` filter should give the same +we have also defined custom Jinja filters that can be used in pipe and system configurations. Some of these filters +produce the same output as the corresponding DTL function (see :ref:`table `), e.g. the ``bytes`` filter should give the same results as the ``bytes`` DTL function. Note that underscores are used in place of dashes in filter names, as -opposed to DTL functions. +opposed to DTL functions. System secrets and subscription-wide secrets can be used inside the filters +with ``secret('secret-name')``. + + .. _custom_jinja_filters: -Custom Jinja filters --------------------- +**decode_jwt** +^^^^^^^^^^^^^^ + +Decodes a JWT given a (public) key. Also supports supplying a JSON Web Key Set (JWKS) URL in place of a key. See the +table below for all supported arguments. .. list-table:: :header-rows: 1 - :widths: 10, 60, 10, 60 + :widths: 10, 10, 60, 10, 5 - * - Filter + * - Argument + - Type - Description - - Arguments - - Example usage + - Default + - Req - * - ``bytes`` - - See the :ref:`bytes ` DTL function. + * - ``key`` + - String + - The public key used for decoding the JWT. - + - Yes, if ``jwks_url`` is not used + + * - ``jwks_url`` + - String + - An HTTPS endpoint containing JSON Web Keys (JWKS). Can be used in place of ``key``. The filter will + decode the JWT using the key(s) provided in the endpoint. - + - Yes, if ``key`` is not used - * - ``base64_encode`` - - See the :ref:`base64-encode ` DTL function. + * - ``algorithms`` + - List + - List of allowed algorithms. + - ``['RS256']`` + - No + + * - ``verify`` + - Boolean + - Whether the JWT signature should be verified. + - ``true`` + - No + + * - ``require`` + - Str, List + - List of claims that must be present. - + - No + + * - ``detached_payload`` + - Bytes + - A payload to verify the signature against. Used for tokens that are not carrying a payload. - + - No - * - ``base64_decode`` - - See the :ref:`base64-decode ` DTL function. + * - ``verify_aud`` + - Boolean + - Check that the ``aud`` claim matches ``audience``. Defaults to the value of ``verify``. - + - No + + * - ``verify_iss`` + - Boolean + - Check that the ``iss`` claim matches ``issuer``. Defaults to the value of ``verify``. - + - No - * - ``datetime`` - - See the :ref:`datetime ` DTL function. + * - ``verify_exp`` + - Boolean + - Check that ``exp`` (expiration) claim value is in the future. Defaults to the value of ``verify``. - + - No + + * - ``verify_iat`` + - Boolean + - Check that ``iat`` (issued at) claim value is an integer. Defaults to the value of ``verify``. - + - No - * - ``datetime_filter`` - - See the :ref:`datetime-format ` DTL function. + * - ``verify_nbf`` + - Boolean + - Check that ``nbf`` (not before) claim value is in the past. Defaults to the value of ``verify``. - + - No + + * - ``strict_aud`` + - Boolean + - Check that the aud claim is a single value (not a list), and matches ``audience`` exactly. + - ``false`` + - No + + * - ``audience`` + - String, List + - The value to check against if ``verify_aud`` is true. + - + - No + + * - ``issuer`` + - String + - The value to check against if ``verify_iss`` is true. - + - No - * - ``decode_jwt`` - - Decodes a JWT given a (public) key. - - key - - ``secret('jwt') | decode_jwt(secret('public_key'))`` \ No newline at end of file + * - ``leeway`` + - Integer, Float + - A time margin in seconds for the JWT expiration check. + - ``0`` + - No + +.. _dtl_filters: + +DTL-equivalent filters +^^^^^^^^^^^^^^^^^^^^^^ + +.. list-table:: + :header-rows: 1 + :widths: 10, 60 + + * - Filter + - Description + + * - ``bytes`` + - See the :ref:`bytes ` DTL function. + + * - ``base64_encode`` + - See the :ref:`base64-encode ` DTL function. + + * - ``base64_decode`` + - See the :ref:`base64-decode ` DTL function. + + * - ``datetime`` + - See the :ref:`datetime ` DTL function. + + * - ``datetime_format`` + - See the :ref:`datetime-format ` DTL function. From ebcdd90fde239d9a668c90ec844f25ea9827ef60 Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Mon, 4 Aug 2025 16:27:08 +0200 Subject: [PATCH 2/3] IS-18431: added back example of decode_jwt usage --- hub/documentation/jinja_filters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst index 58086eb6a6..a918fbace6 100644 --- a/hub/documentation/jinja_filters.rst +++ b/hub/documentation/jinja_filters.rst @@ -20,7 +20,7 @@ with ``secret('secret-name')``. ^^^^^^^^^^^^^^ Decodes a JWT given a (public) key. Also supports supplying a JSON Web Key Set (JWKS) URL in place of a key. See the -table below for all supported arguments. +table below for all supported arguments. Example usage: ``secret('jwt') | decode_jwt(key=secret('public_key'))`` .. list-table:: :header-rows: 1 From 972ab3ca7b61fc3eb3e404d7489b7167b8ffc262 Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Tue, 5 Aug 2025 09:08:39 +0200 Subject: [PATCH 3/3] IS-18431: decode_jwt header styling --- hub/documentation/jinja_filters.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst index a918fbace6..4ad5ad204a 100644 --- a/hub/documentation/jinja_filters.rst +++ b/hub/documentation/jinja_filters.rst @@ -16,7 +16,7 @@ with ``secret('secret-name')``. .. _custom_jinja_filters: -**decode_jwt** +``decode_jwt`` ^^^^^^^^^^^^^^ Decodes a JWT given a (public) key. Also supports supplying a JSON Web Key Set (JWKS) URL in place of a key. See the