docs(generator): document Password secretKeys for multiple keys (#6440)

* docs(generator): document Password secretKeys for multiple keys

Add the secretKeys parameter to the Password generator reference with an
example that produces several uniquely-named passwords in one secret, which is
the purpose-built way to cover the multiple-key use case (cleaner than the
rewrite workaround, which is still linked for the single-key rename case).

Also correct the base64url encoding note: Go's base64.URLEncoding keeps the "="
padding, so the previous "no padding" claim contradicted its own example.

Refs: external-secrets/external-secrets#3823
Signed-off-by: Alexander Chernov <alexander@chernov.it>

* test(generator): cover base64url password encoding

Add a base64url case to the Password generator's TestGenerate, asserting the
URL-safe alphabet and retained "=" padding (Go's base64.URLEncoding). This was
the one encoding branch without coverage.

Refs: external-secrets/external-secrets#3823
Signed-off-by: Alexander Chernov <alexander@chernov.it>

---------

Signed-off-by: Alexander Chernov <alexander@chernov.it>

docs/api/generator/password.md

@@ -21,6 +21,7 @@ You can influence the behavior of the generator by providing the following args
 | symbolCharacters | ~!@#$%^&\*()\_+`-={}\|[]\\:"<>?,./ | Specify the character set that should be used when generating the password. |
 | noUpper          | false                              | disable uppercase characters.                                               |
 | allowRepeat      | false                              | allow repeating characters.                                                 |
+| secretKeys       | `[password]`                       | List of output keys to populate, each with its own unique password. Keys must be non-empty and unique. Defaults to a single `password` key. |
 | encoding         | raw                                | Encoding format for the generated password. Valid values: `raw`, `base64`, `base64url`, `base32`, `hex`. |
 
 ## Example Manifest
@@ -51,6 +52,18 @@ ZRv-k!y6x/V"29:43aErSf$1
 Vk9*mwXE30Q+>H?lY$5I64_q
 ```
 
+## Generating Multiple Passwords
+
+To produce several independent passwords in a single `Kind=Secret`, list the desired output keys under `spec.secretKeys`. Each key is populated with its own unique password, so one generator can back a secret that holds multiple credentials:
+
+```yaml
+{% include 'generator-password-multiple-keys.yaml' %}
+```
+
+This generates a secret with both `key1` and `key2`, each holding a distinct password. All other parameters (`length`, `symbols`, `encoding`, etc.) apply to every generated password.
+
+If you only need to rename the single generated key rather than produce several, use [`rewrite`](../../guides/datafrom-rewrite.md) on the `dataFrom` entry instead (`source: "password"`, `target: "<your-key>"`).
+
 ## Encoding Examples
 
 The password generator supports different encoding formats for the output:
@@ -73,4 +86,4 @@ Key differences between `base64` and `base64url`:
 
 - **base64**: `VGVzdD4+UGFzcz8/d29yZA==` uses `+`, `/`, and `=` for padding
 
-- **base64url**: `VGVzdD4-UGFzcz8_d29yZA==` uses `-`, `_`, and no padding (URL-safe)
+- **base64url**: `VGVzdD4-UGFzcz8_d29yZA==` uses `-` and `_` in place of `+` and `/` (URL-safe), and still uses `=` padding

docs/snippets/generator-password-multiple-keys.yaml

@@ -0,0 +1,24 @@
+apiVersion: generators.external-secrets.io/v1alpha1
+kind: Password
+metadata:
+  name: multiple-passwords
+spec:
+  length: 36
+  secretKeys:
+    - key1
+    - key2
+---
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  name: auth-secrets
+spec:
+  refreshInterval: "30m"
+  target:
+    name: auth-secrets
+  dataFrom:
+    - sourceRef:
+        generatorRef:
+          apiVersion: generators.external-secrets.io/v1alpha1
+          kind: Password
+          name: multiple-passwords

generators/v1/password/password_test.go

@@ -160,6 +160,24 @@ func TestGenerate(t *testing.T) {
 			},
 			wantErr: false,
 		},
+		{
+			// "Test>>Pass??word" exercises the URL-safe alphabet (- and _ in
+			// place of + and /) and keeps "=" padding (Go's base64.URLEncoding).
+			name: "spec with base64url encoding should encode password as url-safe base64 with padding",
+			args: args{
+				jsonSpec: &apiextensions.JSON{
+					Raw: []byte(`{"spec":{"encoding":"base64url"}}`),
+				},
+				passGen: func(len int, symbols int, symbolCharacters string, digits int, noUpper bool, allowRepeat bool,
+				) (string, error) {
+					return "Test>>Pass??word", nil
+				},
+			},
+			want: map[string][]byte{
+				"password": []byte(base64.URLEncoding.EncodeToString([]byte("Test>>Pass??word"))),
+			},
+			wantErr: false,
+		},
 		{
 			name: "secretKeys overrides default output key",
 			args: args{