update docs for file-based auth support (#1692)

Companion for kedacore/keda#7082

Signed-off-by: Jonas-Taha El Sesiy <[email protected]>

Author: elsesiy

content/docs/2.19/authentication-providers/file-path.md

@@ -0,0 +1,44 @@
++++
+title = "File path"
++++
+
+You can read authentication parameters from files mounted in the KEDA operator pod using the `filePath` option. This feature requires the KEDA operator to be configured with a root path for file access.
+
+## Security Constraints
+
+The `filePath` feature has important security constraints:
+
+- **Requires root path configuration** - The KEDA operator must be started with `--filepath-auth-root-path` to define the allowed directory
+- **Path validation** - All file paths are validated to ensure they resolve within the configured root path, preventing access to sensitive system files like service account tokens
+- **Relative paths** - The `filePath` in `ClusterTriggerAuthentication` is treated as a relative path under the configured root path
+
+## Operator Configuration
+
+The KEDA operator requires a command-line argument to enable file-based authentication:
+
+```bash
+--filepath-auth-root-path=/path/to/allowed/files
+```
+
+This path should point to a directory where credential files are mounted. The operator will only read files from within this directory.
+
+## Example
+
+First, ensure the KEDA operator has the root path configured. Then create a `ClusterTriggerAuthentication` referencing files:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ClusterTriggerAuthentication
+metadata:
+  name: file-based-auth
+spec:
+  filePath:
+    - parameter: apiKey           # Required - Defined by the scale trigger
+      path: credentials/api-key   # Required - Path relative to filepath-auth-root-path
+```
+
+**Assumptions:**
+- The path is relative to the `--filepath-auth-root-path` configured for the KEDA operator
+- The credential file exists at `{filepath-auth-root-path}/credentials/api-key`
+- The file contains the raw credential value (not JSON encoded)
+- The file path should match the actual file name, including any extension if present (e.g., `credentials/api-key.txt` if the file is named `api-key.txt`)

content/docs/2.19/concepts/authentication.md

@@ -104,6 +104,9 @@ spec:
   - parameter: {scaledObject-parameter-name}                              # Required.
     name: {env-name}                                                      # Required.
     containerName: {container-name}                                       # Optional. Default: scaleTargetRef.envSourceContainerName of ScaledObject
+  filePath:                                                               # Optional. Define only for ClusterTriggerAuthentication; not supported for TriggerAuthentication.
+  - parameter: {scaledObject-parameter-name}                              # Required.
+    path: {relative-path-to-file}                                         # Required. Relative to --filepath-auth-root-path.
   hashiCorpVault:                                                         # Optional.
     address: {hashicorp-vault-address}                                    # Required.
     namespace: {hashicorp-vault-namespace}                                # Optional. Default is root namespace. Useful for Vault Enterprise
@@ -241,6 +244,30 @@ secretTargetRef:                          # Optional.
 
 **Assumptions:** `namespace` is in the same resource as referenced by `scaleTargetRef.name` in the ScaledObject, unless specified otherwise.
 
+### File(s)
+
+> **Note:** This feature requires the KEDA operator to be configured with `--filepath-auth-root-path`.
+
+You can read authentication parameters from files mounted in the KEDA operator pod. This is useful when credentials are provided via init containers or sidecars that write to a shared volume.
+
+The `filePath` option is only available for `ClusterTriggerAuthentication`, not for namespaced `TriggerAuthentication`.
+
+```yaml
+filePath:                                 # Optional.
+  - parameter: apiKey                     # Required - Defined by the scale trigger
+    path: credentials/api-key             # Required - Path relative to filepath-auth-root-path
+```
+
+**Security constraints:**
+- The path is validated to ensure it resolves within the configured `--filepath-auth-root-path`
+- Access to sensitive paths like `/var/run/secrets/kubernetes.io/serviceaccount/` is blocked
+- Only `ClusterTriggerAuthentication` can use this authentication method
+
+**Assumptions:**
+- The KEDA operator must be started with `--filepath-auth-root-path=/path/to/allowed/files`
+- The credential file exists at `{filepath-auth-root-path}/{path}`
+- The file contains the raw credential value
+
 ### Bound service account token(s)
 
 You can pull one or more service account tokens into the trigger by defining the `serviceAccountName` of the Kubernetes service account.