✨ Keycloak/Admin Portal: Encrypted voter attributes for outputs, exports and login

.devcontainer/.env.remote-deployment.example

@@ -241,6 +241,9 @@ ACTIONS_ADMIN_SECRET=admin
 DEMO_PUBLIC_KEY=eh8l6lsmKSnzhMewrdLXEKGe9KVxxo//QsCT2wwAkBo
 
 # Communication
+# Replace both dummy placeholders: they are rejected as invalid transport names.
+# Production: SMS uses AwsSns; email uses AwsSes or smtp (configure its credentials).
+# Console is test-only and prints full messages, including secrets, into worker logs.
 SMS_TRANSPORT_NAME=dummy
 AWS_SNS_ATTRIBUTES={}
 EMAIL_TRANSPORT_NAME=dummy

.devcontainer/docker-compose-airgap-preparation.yml

@@ -205,6 +205,7 @@ services:
       - 8090:8090
     environment:
       KC_HOSTNAME: ${KC_HOSTNAME}
+      MASTER_SECRET: ${MASTER_SECRET}
       KC_HOSTNAME_STRICT: ${KC_HOSTNAME_STRICT}
       KC_HTTP_PORT: ${KC_HTTP_PORT}
       KC_DB: ${KC_DB}

.devcontainer/docker-compose-base.yml

@@ -434,6 +434,7 @@ services:
     environment:
       RUST_BACKTRACE: ${RUST_BACKTRACE}
       SUPER_ADMIN_TENANT_ID: ${SUPER_ADMIN_TENANT_ID}
+      WINDMILL_SECRET_EXPORT_GRANT_TTL_SECONDS: ${WINDMILL_SECRET_EXPORT_GRANT_TTL_SECONDS:-86400}
       LOG_LEVEL: ${LOG_LEVEL}
       ROCKET_ADDRESS: ${ROCKET_ADDRESS}
       ROCKET_PORT: ${HARVEST_PORT}
@@ -754,6 +755,7 @@ services:
       AWS_S3_ACCESS_KEY: ${AWS_S3_ACCESS_KEY}
       AWS_S3_ACCESS_SECRET: ${AWS_S3_ACCESS_SECRET}
       AWS_S3_JWKS_CACHE_POLICY: ${AWS_S3_JWKS_CACHE_POLICY}
+      WINDMILL_SECRET_EXPORT_GRANT_TTL_SECONDS: ${WINDMILL_SECRET_EXPORT_GRANT_TTL_SECONDS:-86400}
 
       # used by AWS S3 to "load_from_env()". Don't use this in production, not
       # needed. Instead, in production we'll use Web Identity Tokens

.devcontainer/docker-compose-remote.yml

@@ -35,6 +35,7 @@ services:
     restart: always
     environment:
       AMQP_ADDR: ${AMQP_ADDR}
+      MASTER_SECRET: ${MASTER_SECRET}
       KC_HOSTNAME: ${KC_HOSTNAME}
       KC_HOSTNAME_STRICT: ${KC_HOSTNAME_STRICT}
       KC_HTTP_PORT: ${KC_HTTP_PORT}

.devcontainer/docker-compose.yml

@@ -21,6 +21,8 @@ services:
       - 8090:8090
     environment:
       AMQP_ADDR: ${AMQP_ADDR}
+      # Use the same voter-secret encryption key as Harvest and Windmill.
+      MASTER_SECRET: ${MASTER_SECRET}
       KC_HOSTNAME: ${KC_HOSTNAME}
       KC_HOSTNAME_STRICT: ${KC_HOSTNAME_STRICT}
       KC_HTTP_PORT: ${KC_HTTP_PORT}

.devcontainer/keycloak/import/tenant-90505c8a-23a9-4cdf-a26b-4e19f6a097d5.json

@@ -1868,6 +1868,24 @@
         "containerId": "9c67adb8-ae12-43ad-a3f4-2bc275fc888a",
         "attributes": {}
       },
+      {
+        "id": "ef49e644-6ed4-4db9-9688-820993b531db",
+        "name": "voter-secret-attribute-read",
+        "description": "",
+        "composite": false,
+        "clientRole": false,
+        "containerId": "9c67adb8-ae12-43ad-a3f4-2bc275fc888a",
+        "attributes": {}
+      },
+      {
+        "id": "ee774092-f4d3-4ac9-880e-9bed4ff67c08",
+        "name": "voter-secret-attribute-write",
+        "description": "",
+        "composite": false,
+        "clientRole": false,
+        "containerId": "9c67adb8-ae12-43ad-a3f4-2bc275fc888a",
+        "attributes": {}
+      },
       {
         "id": "c5b7b9da-905c-4a00-a016-c0dc35812604",
         "name": "voter-write",
@@ -2490,6 +2508,8 @@
         "election-event-data-tab",
         "user-create",
         "voter-read",
+        "voter-secret-attribute-read",
+        "voter-secret-attribute-write",
         "election-event-reports-tab",
         "election-event-scheduled-tab",
         "election-type-write",

docs/docusaurus/docs/02-election_managers/01-tutorials/07-admin_portal_tutorials_create-voters.md

@@ -8,4 +8,52 @@ SPDX-FileCopyrightText: 2025 Sequent Tech <legal@sequentech.io>
 SPDX-License-Identifier: AGPL-3.0-only
 -->
 
-Content will be added here soon.
+## Create a Voter
+
+1. Open the election event and select the **Voters** tab.
+2. Select **Add**.
+3. Complete the voter fields. Custom fields and their order come from the election event's
+   Keycloak User Profile.
+4. Review the changes and save the voter.
+
+For instructions on defining custom fields, see
+[Adding User Attributes to Keycloak](./99-admin_portal_tutorials_add-user-attributes-to-keycloak.md).
+
+## Secret Voter Fields
+
+Fields configured with `sequent.secret=true` are stored encrypted. They are not available as voter
+list columns, filters, or sort fields, and their stored value is never loaded with the ordinary
+voter record.
+
+The permissions to reveal and edit these fields are independent:
+
+- With `voter-secret-attribute-write`, enter a value when creating a voter or type a replacement
+  while editing one. The previous value does not need to be revealed before replacement.
+- With `voter-secret-attribute-read`, select the eye button to reveal the value. The button is
+  disabled while decryption is in progress. Select it again to hide the value.
+- Both operations also require the corresponding ordinary voter read or write permission.
+
+When editing a voter, an existing unrevealed value is displayed as `••••••••`. Leaving it untouched
+preserves the encrypted value. Use the **Clear** (×) icon at the right of the field and save to remove a value without revealing it. Required fields still need a value. For multivalued fields, each value can be edited, added, or removed separately.
+Review screens mask new and changed secret values rather than repeating them.
+
+A secret can also be used as the login credential with the
+[Multi-Attribute + Password Form](./101-admin_portal_tutorials_multi-attribute-password-login.md#optional-use-an-encrypted-voter-attribute-as-the-credential).
+In that mode, fill the configured secret field (for example, **Mysecret**); the separate Keycloak
+password and password-reset controls do not set or reset that secret.
+
+Revealed values are limited to the open voter editor. Closing the editor removes them from its
+state; the voter list continues to receive only redacted values.
+
+## Export Voters
+
+Select **Export** from the Voters tab to generate a CSV.
+
+- The default export omits every configured secret column. It does not export encrypted envelopes.
+- A user with `voter-secret-attribute-read` can select **Include decrypted secret voter fields** in
+  the confirmation dialog. This adds the secret columns with plaintext values.
+- Treat a decrypted export as sensitive data. The generated document remains protected by the
+  secret-read permission when it is downloaded.
+
+For the complete permission combinations, see
+[Permissions](../02-reference/user-manual/users-and-roles/users-and-roles_permissions.md#secret-voter-field-permissions).

docs/docusaurus/docs/02-election_managers/01-tutorials/08-admin_portal_tutorials_import-voters.md

@@ -8,4 +8,43 @@ SPDX-FileCopyrightText: 2025 Sequent Tech <legal@sequentech.io>
 SPDX-License-Identifier: AGPL-3.0-only
 -->
 
-Content will be added here soon.
+## Prepare the CSV
+
+Use one row per voter. Column names must match the canonical voter and Keycloak User Profile
+attribute names; the display label shown in the Admin Portal is not the import header. For example,
+an attribute named `customerReference` uses this header:
+
+```csv
+username,email,customerReference
+voter-001,voter-001@example.com,REF-12345
+```
+
+Use `|` between values for a multi-valued User Profile attribute. Keep the source CSV private: it
+contains the values in plaintext even when a column is configured as secret.
+
+## Import the Voters
+
+1. Open the election event and select the **Voters** tab.
+2. Select the voter import action and upload the CSV.
+3. Review the task result and correct any reported row or header errors.
+
+## Importing Secret Voter Fields
+
+A CSV can contain a field configured with `sequent.secret=true`. Supply the normal plaintext value;
+do not pre-encrypt it and do not copy an encrypted `seqenc:` value from Keycloak. The import worker
+creates the voter ID and encrypts each non-empty secret cell before it is written to Keycloak.
+
+The initiating user needs `voter-secret-attribute-write` in addition to the normal voter import and
+create access. If the CSV contains a secret header and the user lacks that permission, the whole
+import is rejected and the error identifies the affected columns.
+
+After import:
+
+- ordinary voter views and exports do not return the secret value or its encrypted envelope;
+- users with secret-read permission can reveal it from the voter editor;
+- a decrypted export can include it only when explicitly requested by an authorized user.
+
+See [Protecting a Voter Attribute as Secret](./99-admin_portal_tutorials_add-user-attributes-to-keycloak.md#protecting-a-voter-attribute-as-secret)
+for configuration restrictions, and
+[Permissions](../02-reference/user-manual/users-and-roles/users-and-roles_permissions.md#secret-voter-field-permissions)
+for authorization details.

docs/docusaurus/docs/02-election_managers/01-tutorials/101-admin_portal_tutorials_multi-attribute-password-login.md

@@ -1,6 +1,6 @@
 ---
 id: admin_portal_tutorials_multi_attribute_password_login
-title: Logging In Without a Username (Attribute + Password)
+title: Logging In Without a Username (Attribute + Password or Secret)
 ---
 
 <!--
@@ -14,11 +14,13 @@ By default, voters log in with a username and password. Some elections instead i
 attributes they already know - a date of birth, a national ID - without asking them to remember a
 separate username. This tutorial explains how to configure the **Multi-Attribute + Password Form**
 authenticator so voters log in with one or more configured user attributes plus a password,
-instead of a username.
+instead of a username. The password box can verify either the normal Keycloak password (the
+default) or an explicitly configured encrypted voter attribute.
 
 The authenticator finds every user whose configured attribute(s) match the submitted value(s) -
 **all** configured attributes must match the same user - then checks the submitted password
-against that candidate. Login succeeds only when **exactly one** candidate's password matches.
+against those candidates. With the default `REJECT_AMBIGUOUS` match policy, login succeeds only
+when **exactly one** candidate's credential matches and that account is enabled and not locked out.
 
 A single attribute like date of birth is not unique on its own (many voters share a birth date).
 This still works: the authenticator collects every user with that birth date as candidates and
@@ -30,6 +32,65 @@ second identifying attribute is available.
 
 ## Prerequisites
 
+### Optional: use an encrypted voter attribute as the credential
+
+The default **Credential verification policy** is `PASSWORD`; existing flows do not change.
+To authenticate with a secret voter field instead of a Keycloak password:
+
+1. Configure a custom User Profile attribute, such as `mysecret`, with `sequent.secret=true`,
+   then populate it using the authorized voter editor or CSV importer. Do not enter plaintext
+   directly into Keycloak's attribute editor.
+2. Provision the same 64-character hex master key used by Harvest/Windmill in Keycloak's
+   `MASTER_SECRET` environment variable. The supplied Compose configurations pass the single
+   `MASTER_SECRET` deployment variable to all three services. If Harvest/Windmill use an external
+   vault, inject that vault's existing master key into Keycloak, not a newly generated key.
+   Recreate Keycloak after provisioning the environment variable. Receiving the key does not
+   enable encrypted-attribute login by itself; ordinary `PASSWORD` verification remains the default.
+3. On this authenticator's configuration, set **Credential verification policy** to
+   `SECRET_ATTRIBUTE` and **Encrypted credential attribute** to `mysecret`. Keep ordinary
+   identifying attributes in **User attributes to match**, not the secret attribute.
+4. Keep **Multiple-candidate match policy** at `REJECT_AMBIGUOUS`. `FIRST_MATCH` is rejected in
+   this mode. For IVR, set the same two options on **Multi-Attribute + Password Direct Grant**;
+   its existing single `kind=secret`/`maps_to=password` input carries this credential.
+
+For example, to ask for a date of birth and use `mysecret` as the password:
+
+| Authenticator setting | Value |
+|---|---|
+| User attributes to match | `dateOfBirth` |
+| Credential verification policy | `SECRET_ATTRIBUTE` |
+| Encrypted credential attribute | `mysecret` |
+| Multiple-candidate match policy | `REJECT_AMBIGUOUS` |
+
+Use the exact attribute **name**, not its display label. The secret is the credential, not a lookup
+attribute: do not add `mysecret` to **User attributes to match**. The
+[secret-attribute setup guide](./99-admin_portal_tutorials_add-user-attributes-to-keycloak.md#protecting-a-voter-attribute-as-secret)
+explains the required annotation, permissions and validator restrictions.
+
+The form remains `login.ftl`, and voters enter the credential in the existing `password` field.
+Credential placement, masking/show-hide, autofocus, and `credential-input-policy: "pattern"` keep
+their existing behavior. Pattern formatting is presentation: store the exact submitted credential
+(for digit patterns, the digits, not visual separators). Do not add a second input. A Keycloak
+password is not required or consulted in this mode; password-reset and password-policy operations
+still manage the separate Keycloak password and do not replace this encrypted attribute.
+
+Verification decrypts only the selected attribute of bounded candidates, binds each envelope to
+the tenant/event/voter/attribute, compares fixed-size SHA-256 digests in constant time, and examines
+all stored values. It does not trim or change credential case. Missing, malformed or tampered
+envelopes, missing/wrong keys, disabled/locked accounts and ambiguous matches fail closed without
+password fallback. At most 100 stored values per attribute and 150 UTF-8 bytes per submitted
+credential are accepted. Existing tuple throttling and Keycloak account brute-force protection
+remain active; guessed credentials are never included in the tuple throttle key.
+
+Treat this field as a login credential: anyone authorized to reveal or export it can impersonate
+its voter. Choose high-entropy values, restrict secret-read/write access, enable realm brute-force
+protection, and avoid sending it in report previews, logs or untrusted message transports.
+Email/SMS delivery remains readable; declaring a secret does not encrypt the message. The explicit
+[Console test transport](../02-reference/user-manual/templates/admin_portal_reference_user-manual_templates.md#test-only-console-delivery)
+also prints decrypted values, so use only synthetic credentials when that transport is enabled.
+
+### Standard prerequisites
+
 - Access to the Keycloak Admin Console.
 - The `sequent.message-otp-authenticator.jar` extension deployed in Keycloak's `providers/`
   directory (included in the Sequent Keycloak Docker image by default).
@@ -84,7 +145,7 @@ second identifying attribute is available.
 7. Leave **Existing browser session policy** at `KEEP` for normal login flows. For a shared-device
    flow where each visit must allow a different user to sign in, select `TERMINATE_BEFORE_LOGIN`.
    Opening that login form then ends the user session attached to the browser before credentials
-   are submitted.
+   are submitted. This policy works with both `PASSWORD` and `SECRET_ATTRIBUTE` credential verification.
 8. Click **Save**.
 
 ---
@@ -127,23 +188,25 @@ and explains where realm attributes are edited.
 | No user matches all configured attributes | Generic "invalid credentials" error. |
 | Exactly one candidate, correct password | Login succeeds. |
 | Exactly one candidate, wrong password | Generic "invalid credentials" error - this attempt **is** counted toward that account's Brute Force Detection lockout, same as a standard login. |
-| Exactly one candidate, currently locked out by Brute Force Detection | "Account temporarily/permanently disabled" - no password check is even attempted. |
+| Exactly one candidate, currently locked out by Brute Force Detection | Generic "invalid credentials" error; the locked account cannot log in. |
 | Multiple candidates share the configured attribute(s), and the password matches exactly one | Login succeeds as that user. |
 | Multiple candidates match the password (or none do) | Generic "invalid credentials" error - see the brute-force note below. |
 
-The error is always the same generic message regardless of cause, so a failed attempt never
-reveals which attribute, or the password, was wrong. Every "no match" outcome above (blank field,
-no candidates, wrong password) takes the same time to respond, including a real password-hash
-computation on paths that never actually found a candidate to check - so response time doesn't
-reveal whether any account has the submitted attribute value.
+Authentication failures use a generic message rather than identifying the incorrect attribute or
+credential. Dummy password-hash work on early rejection paths helps reduce timing differences;
+it does **not** guarantee identical response times for an entire login request. In
+`SECRET_ATTRIBUTE` mode, fixed-size digest comparison is constant-time, while database lookup,
+the number of candidates and decryption still contribute to total request time.
 
 > **Note on brute-force protection:** Keycloak's built-in per-account lockout only engages once
 > resolution narrows to a single candidate - the same account that ends up locked out is also the
 > one whose failed attempts get counted, matching how the standard username/password form behaves.
 > When more than one candidate still shares the configured attribute(s), there is no single
 > account a failed attempt can honestly be attributed to, so the counter can't engage for that
-> specific request (a locked-out account among several ambiguous candidates still can't have its
-> password probed, though - it's excluded from consideration before any password is checked).
+> specific request. In `PASSWORD` mode, locked accounts are excluded before password verification.
+> In `SECRET_ATTRIBUTE` mode, enabled but locked accounts still participate in ambiguity detection:
+> locking one account must not make a shared secret authenticate as another voter. A locked
+> account itself can never authenticate.
 > Configuring more attributes narrows the candidate set before the password check, making the
 > single-candidate (fully protected) case the common one; keep **Brute Force Detection** enabled
 > at the realm level regardless.
@@ -200,6 +263,9 @@ touching hash strength.
 When more than one candidate shares the configured attribute value(s) (e.g. several voters born on
 the same date), **Multiple-candidate match policy** governs how the submitted password picks one:
 
+`SECRET_ATTRIBUTE` mode requires `REJECT_AMBIGUOUS`; the `FIRST_MATCH` option below applies only
+to ordinary `PASSWORD` verification.
+
 - **`REJECT_AMBIGUOUS`** (default): checks every candidate's password. Only succeeds if the
   submitted password matches **exactly one** of them; if it matches more than one, the request
   fails generically, the same as if none had matched.