From c7af26918a702ac935bc1e7b264c355accda79a6 Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Thu, 20 Feb 2025 14:29:12 +0100 Subject: [PATCH 1/3] IS-18159: add new page for documenting Jinja filters --- hub/documentation/jinja_filters.rst | 54 +++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 hub/documentation/jinja_filters.rst diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst new file mode 100644 index 0000000000..2116cad11b --- /dev/null +++ b/hub/documentation/jinja_filters.rst @@ -0,0 +1,54 @@ +.. _jinja_filters_section: + + +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 +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, 40 + + * - Filter + - Description + - Arguments + - Example usage + + * - ``bytes`` + - See the :ref:`bytes ` DTL function. + - None + - + + * - ``base64_encode`` + - See the :ref:`base64-encode ` DTL function. + - None + - + + * - ``base64_decode`` + - See the :ref:`base64-decode ` DTL function. + - None + - + + * - ``datetime`` + - See the :ref:`datetime ` DTL function. + - + - + + * - ``datetime_filter`` + - See the :ref:`datetime-format ` DTL function. + - + - + + * - ``decode_jwt`` + - Decodes a JWT given a (public) key. + - key + - ``decode_jwt(secret('public_key'))`` \ No newline at end of file From 0f04d34caff2872241be8ffe9e321561da26a6e2 Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Thu, 27 Feb 2025 14:39:55 +0100 Subject: [PATCH 2/3] IS-18159: using new Jinja filter page in references and added changelog item --- hub/changelog.rst | 11 ++++++++++ hub/documentation/jinja_filters.rst | 12 +++++----- .../pipes/configuration-sources-http.rst | 12 +++++++++- .../systems/configuration-systems-rest.rst | 22 ++++--------------- 4 files changed, 32 insertions(+), 25 deletions(-) diff --git a/hub/changelog.rst b/hub/changelog.rst index cd819df27d..72da9769ff 100644 --- a/hub/changelog.rst +++ b/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 ` which documents our available Jinja filters. + + .. _changelog_2025-02-06: 2025-02-06 diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst index 2116cad11b..6195844e38 100644 --- a/hub/documentation/jinja_filters.rst +++ b/hub/documentation/jinja_filters.rst @@ -12,11 +12,11 @@ opposed to DTL functions. .. _custom_jinja_filters: Custom Jinja filters ----------- +-------------------- .. list-table:: :header-rows: 1 - :widths: 10, 60, 10, 40 + :widths: 10, 60, 10, 60 * - Filter - Description @@ -25,17 +25,17 @@ Custom Jinja filters * - ``bytes`` - See the :ref:`bytes ` DTL function. - - None + - - * - ``base64_encode`` - See the :ref:`base64-encode ` DTL function. - - None + - - * - ``base64_decode`` - See the :ref:`base64-decode ` DTL function. - - None + - - * - ``datetime`` @@ -51,4 +51,4 @@ Custom Jinja filters * - ``decode_jwt`` - Decodes a JWT given a (public) key. - key - - ``decode_jwt(secret('public_key'))`` \ No newline at end of file + - ``secret('jwt') | decode_jwt(secret('public_key'))`` \ No newline at end of file diff --git a/hub/documentation/service-configuration/pipes/configuration-sources-http.rst b/hub/documentation/service-configuration/pipes/configuration-sources-http.rst index 63f616f535..6909c1f68a 100644 --- a/hub/documentation/service-configuration/pipes/configuration-sources-http.rst +++ b/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 `_. 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 `_. + 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 ` 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:: diff --git a/hub/documentation/service-configuration/systems/configuration-systems-rest.rst b/hub/documentation/service-configuration/systems/configuration-systems-rest.rst index dd33728485..184794e8db 100644 --- a/hub/documentation/service-configuration/systems/configuration-systems-rest.rst +++ b/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 ` of using ``custom_auth`` towards various systems. Some of +these examples make use of our :ref:`Jinja filters ` for more advanced configuration. -There are several examples :ref:`here ` 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 ` can + must evaluate to a date, e.g. "2025-01-25T10:42:24". :ref:`Jinja filters ` 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 ` for more examples on systems that use ``custom_auth``. -.. _rest_system_jinja_filters: - -Supported Jinja filters -^^^^^^^^^^^^^^^^^^^^^^^ -In addition to the `built-in filters `_, -the REST system also supports these custom filters: - -``datetime``: See the :ref:`datetime ` DTL function. An example on using this filter can be -found :ref:`here `. - -``datetime_format``: See the :ref:`datetime-format ` DTL function. An example on using -this filter can be found :ref:`here `. - - - .. _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", From ac7e461a76c789051066953f295c3eb8edfe994a Mon Sep 17 00:00:00 2001 From: Hans Glad Date: Thu, 27 Feb 2025 14:46:15 +0100 Subject: [PATCH 3/3] IS-18159: make Jinja filter page an orphan for now --- hub/documentation/jinja_filters.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/hub/documentation/jinja_filters.rst b/hub/documentation/jinja_filters.rst index 6195844e38..5a04bec868 100644 --- a/hub/documentation/jinja_filters.rst +++ b/hub/documentation/jinja_filters.rst @@ -1,3 +1,5 @@ +:orphan: + .. _jinja_filters_section: