Document platform-managed authentications

src/content/docs/guides/platform-management/configure-authentications.mdx

@@ -0,0 +1,89 @@
+---
+title: Configure authentications
+---
+
+This guide shows you how to configure named HTTP authentication recipes in the
+Tenzir Platform so that pipeline operators like <Op>from_http</Op> and
+<Op>to_http</Op> can authenticate outbound requests by name. Each
+authentication combines a non-secret configuration (client IDs, token URLs,
+scopes, headers) with references to one or more workspace secrets, which the
+connected Tenzir Nodes resolve at runtime.
+
+For background on how secret values are stored and resolved, see the
+[Secrets explanations page](/explanations/secrets).
+
+:::caution[Built-in secret store required]
+Authentications currently require the workspace to use the platform's built-in
+secret store. Workspaces whose default store is AWS Secrets Manager or
+HashiCorp Vault can't create authentications yet.
+:::
+
+## Add an authentication
+
+Open the workspace settings by clicking the gear icon in the workspace
+selector, then switch to the **Authentications** tab:
+
+![Authentications list](authentications.png)
+
+Click **Add authentication** and pick one of the supported strategies:
+
+| Strategy                       | Public configuration                  | Secret reference |
+| ------------------------------ | ------------------------------------- | ---------------- |
+| **OAuth · client credentials** | client ID, token URL, scopes, audience | client secret    |
+| **Basic auth**                 | username                              | password         |
+| **API key**                    | header name (defaults to `X-Api-Key`) | API key value    |
+| **Bearer token**               | none                                  | token            |
+
+For the secret field, pick an existing workspace secret from the picker rather
+than typing a value. The picker also offers an inline
+**+ Create a new secret…** entry that opens the secret modal and binds the
+new entry to the field after you save it.
+
+![Selecting or creating a workspace secret](authentications-picker.png)
+
+## Use an authentication in a pipeline
+
+After you save the authentication, reference it by name from a pipeline
+operator:
+
+```tql
+from_http "https://api.example.com/v1/data", auth="events-read"
+```
+
+When the operator runs, the node resolves the name in two places, in order:
+first under [`tenzir.auth`](/reference/node/configuration) in the local
+`tenzir.yaml`, then in the connected platform's authentication store. The
+first match wins. The node resolves the referenced secret through the same
+encrypted channel it uses for standalone secrets, then applies the
+strategy-specific headers (`Authorization: Bearer …`,
+`Authorization: Basic …`, a custom header for API keys, or an OAuth token-fetch
+loop for client credentials).
+
+## Edit or rotate an authentication
+
+In edit mode you can only change the secret reference. The non-secret fields
+and the strategy are locked, because nodes cache them per `(workspace, name)`
+until they restart. Changing those fields without a restart would leave the
+node out of sync with the platform's view of the authentication.
+
+You have two safe ways to rotate a credential:
+
+- **Replace the secret value in place.** Update the referenced secret in
+  **Settings > Secrets** (same name, new value). Nodes pick up the new value
+  on the next pipeline run without an authentication edit.
+- **Rebind the authentication to a different secret.** Open the authentication
+  in edit mode and pick a different workspace secret in the picker.
+
+## Recover from a missing secret
+
+If you delete a secret that an authentication still references, the platform
+keeps the authentication and flags the list row with a **missing secret**
+warning. The picker shows the same warning in edit mode. To clear it, bind the
+authentication to an existing secret or create a new secret inline.
+
+## See Also
+
+- <Op>from_http</Op>
+- <Op>to_http</Op>
+- <Explanation>secrets</Explanation>
+- <Guide>platform-setup/configure-secret-store</Guide>

src/content/docs/reference/operators/from_http.mdx

@@ -12,9 +12,10 @@ Sends an HTTP/1.1 request and returns the response as events.
 
 ```tql
 from_http url:string, [method=string, body=record|string|blob, encode=string,
-          headers=record, error_field=field, paginate=string|lambda,
-          paginate_delay=duration, connection_timeout=duration,
-          max_retry_count=int, retry_delay=duration, tls=record]
+          headers=record, auth=string, error_field=field,
+          paginate=string|lambda, paginate_delay=duration,
+          connection_timeout=duration, max_retry_count=int,
+          retry_delay=duration, tls=record]
           [{ … }]
 ```
 
@@ -396,4 +397,5 @@ Tenzir emits a diagnostic before each retry with the reason and wait time.
 - <Guide>collecting/fetch-via-http-and-apis</Guide>
 - <Guide>enrichment/enrich-with-threat-intel</Guide>
 - <Guide>enrichment/use-lookup-tables</Guide>
+- <Guide>platform-management/configure-authentications</Guide>
 - <Integration>http</Integration>

src/content/docs/reference/operators/to_http.mdx

@@ -12,9 +12,10 @@ import HttpClientOptions from '@partials/operators/HttpClientOptions.mdx';
 Sends events as a single HTTP request to a webhook or API endpoint.
 
 ```tql
-to_http url:string, [method=string, headers=record, buffer_all=bool,
-        timeout=duration, tls=record, connection_timeout=duration,
-        max_retry_count=int, retry_delay=duration] { … }
+to_http url:string, [method=string, headers=record, auth=string,
+        buffer_all=bool, timeout=duration, tls=record,
+        connection_timeout=duration, max_retry_count=int,
+        retry_delay=duration] { … }
 ```
 
 ## Description
@@ -223,4 +224,5 @@ flushing.
 - <Op>every</Op>
 - <Guide>tenzir-v6-migration</Guide>
 - <Guide>collecting/fetch-via-http-and-apis</Guide>
+- <Guide>platform-management/configure-authentications</Guide>
 - <Integration>http</Integration>

src/partials/operators/HttpClientOptions.mdx

@@ -4,6 +4,37 @@ Record of headers to send with the request. Each value is resolved as a
 [secret](/explanations/secrets), so you can pass secret names to avoid
 hardcoding tokens or API keys directly in the pipeline.
 
+### `auth = string (optional)`
+
+Name of a configured authentication that the node applies to the request. The
+node resolves the name in two places, in order: first under
+[`tenzir.auth`](/reference/node/configuration) in the local `tenzir.yaml`,
+then in the connected Tenzir Platform's
+[authentication store](/guides/platform-management/configure-authentications).
+The first match wins.
+
+```tql
+from_http "https://api.example.com/v1/data", auth="events-read"
+```
+
+Rotating a referenced secret in the platform takes effect on the next request
+without restarting the node. The strategy-specific public fields (such as
+`client_id` or `token_url`) are cached per `(workspace, name)` until the node
+restarts.
+
+`auth` writes the resulting headers after `headers`, so when both set the same
+header, the `auth` value wins. For example, this request sends
+`Authorization: Bearer <token-from-auth>`, not `Bearer foo`:
+
+```tql
+from_http "https://api.example.com/v1/data",
+  headers={Authorization: "Bearer foo"},
+  auth="events-bearer"
+```
+
+This is true for every strategy, since each one ends up setting the
+`Authorization` header (or the API key's custom header) after `headers` runs.
+
 ### `timeout = duration (optional)`
 
 Timeout for the overall request.

src/sidebar.ts

@@ -67,6 +67,7 @@ export const guides = [
           "guides/platform-management/manage-organization-members",
           "guides/platform-management/manage-organization-workspaces",
           "guides/platform-management/configure-workspaces",
+          "guides/platform-management/configure-authentications",
           "guides/platform-management/configure-dashboards",
           "guides/platform-management/use-ephemeral-nodes",
         ],

tenzir.yaml.example

@@ -437,6 +437,36 @@ tenzir:
   secrets:
     # my-secret-name: my-secret-value
 
+  # Named authentication recipes that the `from_http` and `to_http` operators
+  # can reference via `auth="<name>"`. Each entry must carry a `name` and a
+  # `strategy`; the remaining keys are strategy-specific. The node resolves a
+  # name against this list first and then against the connected Tenzir
+  # Platform's authentication store; the first match wins.
+  #
+  # Sensitive values are written as literal strings here. Protect this config
+  # the same way you'd protect any credentials file (file mode 0600, owned by
+  # the node user). Platform-managed authentications keep credentials off
+  # disk entirely.
+  auth:
+    # - name: events-oauth
+    #   strategy: oauth-client-credentials      # or just "oauth"
+    #   client_id: client-id-9b4f
+    #   client_secret: rA8nXg9LxQ4kP2hT
+    #   token_url: https://auth.example.com/oauth/token
+    #   scopes: [events.read]
+    #   audience: https://api.example.com       # optional; required if scopes is empty
+    # - name: events-basic
+    #   strategy: basic
+    #   username: events-bot
+    #   password: hunter2
+    # - name: events-api-key
+    #   strategy: api-key
+    #   header_name: X-Api-Key                  # optional; this is the default
+    #   api_key: a1b2c3d4e5f60718
+    # - name: events-bearer
+    #   strategy: bearer-static
+    #   token: eyJhbGciOiJIUzI1NiJ9.payload.sig
+
   # Configure the interval for experimental trimming of unused memory.
   malloc-trim-interval: 10min