Feat(Datakit): Use a dynamic internal auth endpoint to inject request headers before proxying a request (#3656)

* Add datakit dynamic url exampel

* Add docs for datakit call node proxy options

* small changes

* Add docs for datakit call node url-encoded support

* fixes

---------

Co-authored-by: Angel <angel.guarisma@konghq.com>
Co-authored-by: Angel <Guaris@users.noreply.github.com>

Author: iykon

app/_kong_plugins/datakit/examples/authenticate-third-party-with-dynamic-url.yaml

@@ -0,0 +1,69 @@
+description: |
+  Use a dynamic internal auth endpoint to inject request headers before proxying a request.
+
+extended_description: |
+  Use a dynamic internal auth endpoint to inject request headers before proxying a request.
+
+  This example contains the following nodes:
+  1. The node `STATIC_INPUTS` sets some static values that will be used as inputs to other nodes.
+  1. The node `BUILD_HEADERS` fetches an API key from the client query and injects it into the request headers that will be sent to the auth service.
+  1. The node `BUILD_URL` constructs the auth service URL dynamically based on the request path parameter from request headers.
+  1. The node `AUTH_REQUEST` makes a POST request to the auth service.
+  1. The node `UPSTREAM_AUTH_HEADER` composes an Authorization header from the access token received from the auth service and 
+  adds it to the service request headers before proxying the request.
+
+title: Authenticate Kong to a third-party service resolved at runtime
+weight: 900
+
+config:
+  nodes:
+  - name: STATIC_INPUTS
+    type: static
+    values:
+      headers:
+        Content-Type: application/x-www-form-urlencoded
+      body: grant_type=client_credentials
+
+  - name: BUILD_HEADERS
+    type: jq
+    inputs:
+      headers: STATIC_INPUTS.headers
+      query: request.query
+    jq: |
+      .headers * {
+        "X-Api-Key": (.query.api_key // "none")
+      }
+  
+  - name: BUILD_URL
+    type: jq
+    input: request.headers
+    jq: |
+      "https://my-token-service/" + .path + "/auth-token"
+
+  - name: AUTH_REQUEST
+    type: call
+    inputs:
+      headers: BUILD_HEADERS
+      body: STATIC_INPUTS.body
+      url: BUILD_URL
+    url: "https://my-token-service/auth-token"
+    method: POST
+
+  - name: UPSTREAM_AUTH_HEADER
+    type: jq
+    input: AUTH_REQUEST.body
+    output: service_request.headers
+    jq: |
+      {
+        Authorization: (.token_type + " " + .access_token)
+      }
+
+tools:
+  - deck
+  - admin-api
+  - konnect-api
+  - kic
+  - terraform
+
+min_version:
+  gateway: '3.13'

app/_kong_plugins/datakit/examples/authenticate-third-party.yaml

@@ -21,7 +21,9 @@ config:
     values:
       headers:
         Content-Type: application/x-www-form-urlencoded
-      body: grant_type=client_credentials
+      body:
+        grant_type: client_credentials
+        client_id: my_client_id
 
   - name: BUILD_HEADERS
     type: jq

app/_kong_plugins/datakit/index.md

@@ -77,6 +77,8 @@ rows:
     description: "Leverage the `cache` and `branch` nodes to conditionally store or retrieve cache items."
   - usecase: "[Transform XML into JSON, or JSON into XML](/plugins/datakit/examples/convert-json-to-xml-and-back/)"
     description: "Transform JSON requests into XML so you can send the data to a SOAP service, then transform the resulting XML back into JSON."
+  - usecase: "[Third-party auth with dynamic url](/plugins/datakit/examples/authenticate-third-party-with-dynamic-url/)"
+    description: Dynamically resolve an internal authentication endpoint and inject the necessary request headers prior to proxying the request.
 {% endtable %}
 <!--vale on-->
 
@@ -520,6 +522,11 @@ rows:
       * `body`: Request body
       * `headers`: Request headers
       * `query`: Key-value pairs to encode as the request query string
+      * `url`: The request URL resolved at runtime
+      * `https_proxy`: The HTTPS proxy URL to use for the request
+      * `http_proxy`: The HTTP proxy URL to use for the request
+      * `proxy_auth_username`: The username to authenticate with the proxy
+      * `proxy_auth_password`: The password to authenticate with the proxy
     outputs: |
       * `body`: The response body
       * `headers`: The response headers
@@ -655,13 +662,26 @@ Send a POST request with a JSON body:
     name: Datakit
 ```
 
+Perform a request through a proxy server:
+
+```yaml
+- name: CALL
+  type: call
+  url: https://example.com/foo
+  inputs:
+    https_proxy: http://my-proxy.example.com:8080
+    proxy_auth_username: my-username
+    proxy_auth_password: my-password
+```
+
 Call nodes are used in most datakit workflows. For complete examples, see:
 * [Third-party auth](/plugins/datakit/examples/authenticate-third-party/)
 * [Request multiplexing](/plugins/datakit/examples/combine-two-apis-into-one-response/)
 * [Manipulate request headers](/plugins/datakit/examples/manipulate-request-headers/)
 * [Authentication with Vault secrets](/plugins/datakit/examples/authenticate-with-vault-secret/)
 * [Conditionally fetch or store cache data](/plugins/datakit/examples/conditionally-store-cached-items/)
 * [Transform XML into JSON, or JSON into XML](/plugins/datakit/examples/convert-json-to-xml-and-back/)
+* [Third-party auth with dynamic url](/plugins/datakit/examples/authenticate-third-party-with-dynamic-url/)
 
 #### Automatic JSON body handling
 
@@ -707,6 +727,32 @@ the endpoint returns a non-2xx status code. It will also fail if the endpoint
 returns a JSON mime-type in the `Content-Type` header if the response body is
 not valid JSON.
 
+#### Resolve URL at runtime
+
+A `call` node defines its `url` statically during configuration. To substitute a different endpoint at runtime, pass a value via the `url` input. If the input is `nil`, Datakit automatically reverts to the configured static URL.
+
+For example:
+
+```yaml
+- name: DYNAMIC_URL
+  type: call
+  url: https://example.com/default
+  inputs:
+    url: request.body
+```
+
+#### Proxy options
+The `call` node supports performing requests via a proxy server. This is controlled by proxy options. See above example for more details.
+
+#### Request body encoding
+Call node supports following content types for request body encoding:
+* `application/json`
+* `application/x-www-form-urlencoded`
+
+By default, if the body input is an object, it will be encoded as JSON. To override this behavior and use `application/x-www-form-urlencoded`, set the `Content-Type` header accordingly in the `headers` input for the call node.
+
+See [Third-party auth](/plugins/datakit/examples/authenticate-third-party/) for an example of using `application/x-www-form-urlencoded` request body encoding.
+
 #### Limitations
 
 Due to platform limitations, the `call` node can't be executed after proxying a
@@ -1019,6 +1065,7 @@ For more detailed examples, see:
 * [Request multiplexing](/plugins/datakit/examples/combine-two-apis-into-one-response/)
 * [Manipulate request headers](/plugins/datakit/examples/manipulate-request-headers/)
 * [Authentication with Vault secrets](/plugins/datakit/examples/authenticate-with-vault-secret/)
+* [Third-party auth with dynamic url](/plugins/datakit/examples/authenticate-third-party-with-dynamic-url/)
 
 ### Exit node
 
@@ -1374,6 +1421,7 @@ For more detailed examples, see:
 * [Third-party auth](/plugins/datakit/examples/authenticate-third-party/)
 * [Authentication with Vault secrets](/plugins/datakit/examples/authenticate-with-vault-secret/)
 * [Conditionally fetch or store cache data](/plugins/datakit/examples/conditionally-store-cached-items/)
+* [Third-party auth with dynamic url](/plugins/datakit/examples/authenticate-third-party-with-dynamic-url/)
 
 ### XML to JSON node {% new_in 3.13 %}