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..4ad5ad204a 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. Example usage: ``secret('jwt') | decode_jwt(key=secret('public_key'))`` .. 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.