IS-18159: Documenting custom Jinja filters

hub/changelog.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+.. _changelog_2025-02-27:
+
+2025-02-27
+----------
+* Added new Jinja filters: ``bytes``, ``base64_encode``, ``base64_decode``, ``datetime``, and ``datetime_filter``.
+  These filters work the same way as the corresponding DTL functions and should produce the same output.
+* Added a new ``decode_jwt`` Jinja filter which decodes a JWT given a public key. The output is the decoded JWT in JSON
+  format.
+* Added a new :ref:`section <jinja_filters_section>` which documents our available Jinja filters.
+
+
 .. _changelog_2025-02-06:
 
 2025-02-06

hub/documentation/jinja_filters.rst

@@ -0,0 +1,56 @@
+:orphan:
+
+.. _jinja_filters_section:
+
+
+Jinja filters
+=============
+In addition to the `built-in filters <https://jinja.palletsprojects.com/en/stable/templates/#list-of-builtin-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
+results as the ``bytes`` DTL function. Note that underscores are used in place of dashes in filter names, as
+opposed to DTL functions.
+
+.. _custom_jinja_filters:
+
+Custom Jinja filters
+--------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10, 60, 10, 60
+
+   * - Filter
+     - Description
+     - Arguments
+     - Example usage
+
+   * - ``bytes``
+     - See the :ref:`bytes <bytes_dtl_function>` DTL function.
+     -
+     -
+
+   * - ``base64_encode``
+     - See the :ref:`base64-encode <base64_encode_dtl_function>` DTL function.
+     -
+     -
+
+   * - ``base64_decode``
+     - See the :ref:`base64-decode <base64_decode_dtl_function>` DTL function.
+     -
+     -
+
+   * - ``datetime``
+     - See the :ref:`datetime <datetime_dtl_function>` DTL function.
+     -
+     -
+
+   * - ``datetime_filter``
+     - See the :ref:`datetime-format <datetime_format_dtl_function>` DTL function.
+     -
+     -
+
+   * - ``decode_jwt``
+     - Decodes a JWT given a (public) key.
+     - key
+     - ``secret('jwt') | decode_jwt(secret('public_key'))``

hub/documentation/service-configuration/pipes/configuration-sources-http.rst

@@ -152,7 +152,17 @@ Properties
 
    * - ``validation_expression``
      - String
-     - This property allows custom request validation for receiver endpoints. This is particularly useful when clients cannot use JWT tokens for authentication. The string must be a `Jinja template <https://jinja.palletsprojects.com/en/3.1.x/templates/#tests>`_. The Jinja template is rendered for each incoming request. If it renders as an empty string then the request is accepted, otherwise the rendered string will be reported as an error in the response. The context allows using the ``secret`` function to access values of secrets. The named variables ``url``, ``request_params`` and ``request_headers`` are available to the template.  Example: ``"{{ '' if request_headers['X-Sesam-Authorization'] == secret('webhook_secret') else 'Invalid authorization header value' }}"``.
+     - This property allows custom request validation for receiver endpoints. This is particularly useful when clients
+       cannot use JWT tokens for authentication. The string must be a `Jinja template <https://jinja.palletsprojects.com/en/3.1.x/templates/#tests>`_.
+       The Jinja template is rendered for each incoming request. If it renders as an empty string then the request is
+       accepted, otherwise the rendered string will be reported as an error in the response. The context allows using
+       the ``secret`` function to access values of secrets. The named variables ``url``, ``request_params`` and
+       ``request_headers`` are available to the template. Example:
+       ``"{{ '' if request_headers['X-Sesam-Authorization'] == secret('webhook_secret') else 'Invalid authorization header value' }}"``.
+
+       Our :ref:`custom Jinja filters <custom_jinja_filters>` can also be used for more advanced validation, such as
+       decoding an incoming JWT with ``decode_jwt``. Example:
+       ``"{% if (request_headers['header-with-jwt'] | decode_jwt(secret('public_key'))) %}{% else %}FAIL!{% endif %}"``
 
        .. NOTE::
 

hub/documentation/service-configuration/systems/configuration-systems-rest.rst

@@ -523,8 +523,9 @@ These standardized expiry-related properties are also added to the ``token`` obj
        is used.
 
 
+There are several examples :ref:`here <custom_auth_examples>` of using ``custom_auth`` towards various systems. Some of
+these examples make use of our :ref:`Jinja filters <jinja_filters_section>` for more advanced configuration.
 
-There are several examples :ref:`here <custom_auth_examples>` of using ``custom_auth`` towards various systems.
 The ``custom_auth`` section uses the following sub-properties:
 
 .. list-table::
@@ -550,7 +551,7 @@ The ``custom_auth`` section uses the following sub-properties:
      - If the token is expected to contain a timestamp for when the access token expires,
        this should be set to the name of the property that contains that timestamp. This needs to be a Jinja expression,
        e.g. ``{{ token.expirationDate }}`` if the name of the property is ``expirationDate``. Note that the expression
-       must evaluate to a date, e.g. "2025-01-25T10:42:24". :ref:`Jinja filters <rest_system_jinja_filters>` can
+       must evaluate to a date, e.g. "2025-01-25T10:42:24". :ref:`Jinja filters <jinja_filters_section>` can
        be used to convert any expiration values that are not given as a date, for example if it is provided as a Unix
        epoch.
        If ``expires_in_expression`` is also set, the ``expires_at_expression`` will take priority if it evaluates to a
@@ -729,21 +730,6 @@ system that uses the bearer token format:
 See the :ref:`example configurations <custom_auth_examples>` for more examples on systems that use ``custom_auth``.
 
 
-.. _rest_system_jinja_filters:
-
-Supported Jinja filters
-^^^^^^^^^^^^^^^^^^^^^^^
-In addition to the `built-in filters <https://jinja.palletsprojects.com/en/stable/templates/#list-of-builtin-filters>`_,
-the REST system also supports these custom filters:
-
-``datetime``:  See the :ref:`datetime <datetime_dtl_function>` DTL function. An example on using this filter can be
-found :ref:`here <rest_system_arcgis_un_example>`.
-
-``datetime_format``: See the :ref:`datetime-format <datetime_format_dtl_function>` DTL function. An example on using
-this filter can be found :ref:`here <rest_system_arcgis_un_example>`.
-
-
-
 .. _rest_system_example:
 
 Example configuration
@@ -826,7 +812,7 @@ access token:
         "url_pattern": "https://api.tripletex.io/v2/%s",
         "verify_ssl": true,
         "headers": {
-            "Authorization": "Basic {{ ( ('0:' + token.token) | tobytes(encoding='utf-8') | b64encode).decode() }}"
+            "Authorization": "Basic {{ ( ('0:' + token.token) | bytes | base64_encode) }}"
         },
         "custom_auth": {
             "get_token_operation": "fetch-session-token",