From 41e0714ca5f75d6b5a72968133f8a2d24f0817d7 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Sun, 15 Feb 2026 13:21:09 -0800
Subject: [PATCH] docs: update S3 and Security configurations for IAM defaults
 and zero-config setup

---
 S3-Configuration.md       | 45 +++++++++++++++++++++++++++++++++------
 Security-Configuration.md |  2 ++
 2 files changed, 41 insertions(+), 6 deletions(-)

diff --git a/S3-Configuration.md b/S3-Configuration.md
index bf15593..02e35cb 100644
--- a/S3-Configuration.md
+++ b/S3-Configuration.md
@@ -6,8 +6,24 @@ SeaweedFS S3 gateway has two separate configuration systems for different purpos
 
 | Option | Purpose | Use When |
 |--------|---------|----------|
-| `-s3.config` / `-config` | Basic S3 credentials (identities, access keys, actions) | You need simple user authentication with access keys |
-| `-s3.iam.config` / `-iam.config` | Advanced IAM (STS, OIDC, policies, roles) | You need OIDC integration, role-based access, or AWS IAM-style policies |
+| **No Config** | **Zero Configuration** | **Simplest way to use STS features immediately** |
+| `-s3.config` | Basic S3 credentials | You need simple user authentication with access keys |
+| `-s3.iam.config` | Advanced IAM (STS, OIDC) | You need OIDC integration or role-based access |
+
+## Zero Configuration (Simplest)
+
+`weed s3` enables **Advanced IAM (STS)** by default with secure, auto-generated keys.
+
+**Use this for**: Immediate access to STS features like `AssumeRoleWithWebIdentity` (e.g., for Kubernetes workloads) without any setup.
+
+```bash
+# S3 server starts with STS enabled, allowing both anonymous and STS access
+weed s3 -filer=localhost:8888
+```
+
+### Security & Persistence
+-   **Default Effect: Allow**: This defaults to **Open Access** (same as legacy behavior). It does **not** secure your data by default. To enforce access control, you must provide a config file with `"defaultEffect": "Deny"`.
+-   **Policy Store: Memory**: By default, policies are stored in memory and **lost on restart**. This ensures "Zero Config" instances are isolated and don't accidentally enforce cluster-wide policies. For persistent policies, use `-s3.iam.config` and configure `"storeType": "filer"`.
 
 ## Basic Credentials (`-s3.config`)
 
@@ -85,10 +101,10 @@ weed mini -s3.iam.config=/path/to/iam.json
 ```json
 {
   "sts": {
-    "tokenDuration": "1h",
-    "maxSessionLength": "12h",
-    "issuer": "seaweedfs-sts",
-    "signingKey": "base64-encoded-32-byte-key"
+    "tokenDuration": "1h",       // Optional, default: "1h"
+    "maxSessionLength": "12h",   // Optional, default: "12h"
+    "issuer": "seaweedfs-sts",   // Optional, default: "seaweedfs-sts"
+    "signingKey": "base64-..."   // Optional, auto-fallback if missing
   },
   "providers": [
     {
@@ -132,6 +148,23 @@ weed mini -s3.iam.config=/path/to/iam.json
 | `providers` | OIDC identity providers (Keycloak, Okta, Auth0, etc.) |
 | `policies` | AWS IAM-style policy documents |
 | `roles` | IAM roles with trust policies for role assumption |
+ 
+ ### STS Configuration & Defaults
+ 
+ The `sts` section is optional. If omitted or partially configured, the following defaults apply:
+ 
+ - `tokenDuration`: Defaults to `1h`
+ - `maxSessionLength`: Defaults to `12h`
+ - `issuer`: Defaults to `seaweedfs-sts`
+ 
+ **Signing Key Fallback Strategy**:
+ 
+ If `signingKey` is not provided in the IAM config, SeaweedFS attempts to find a key in the following order:
+ 
+ 1.  **Filer Signing Key**: The `jwt.filer_signing.key` from server configuration (`security.toml` or CLI).
+ 2.  **SSE-S3 Master Key (KEK)**: If the filer key is missing, it falls back to the cluster-wide SSE-S3 Master Key (stored in filer at `/etc/s3/sse_kek`).
+     -   **Auto-Generation**: This key is automatically generated if it does not exist, ensuring a fallback is always available in a healthy cluster.
+     -   *Security Note*: A specific `seaweedfs-sts-signing-key` is derived from the master KEK using HKDF-SHA256 to ensure cryptographic isolation between STS and SSE-S3.
 
 > **Important**: The `-s3.iam.config` does NOT support the `identities` field. For basic user credentials, use `-s3.config` instead.
 
diff --git a/Security-Configuration.md b/Security-Configuration.md
index 36505cc..f91f644 100644
--- a/Security-Configuration.md
+++ b/Security-Configuration.md
@@ -54,6 +54,8 @@ expires_after_seconds = 10           # seconds
 # - f.e. the S3 API Shim generates the JWT
 # - the Filer server validates the JWT on writing
 # the jwt defaults to expire after 10 seconds.
+#
+# NOTE: This key is ALSO used as a fallback signing key for S3 STS if s3.iam.config does not specify a signingKey.
 [jwt.filer_signing]
 key = ""
 expires_after_seconds = 10           # seconds