feat(logto): add local admin credential parity

Add configurable local Logto admin email and username, generate a dedicated Logto admin password secret, expose status/help/docs plumbing, and update smoke credentials to read the Logto secret.

Author: terion-name

ansible/roles/idp_logto/defaults/main.yml

@@ -10,6 +10,8 @@ terrarium_logto_instance_image: ubuntu:24.04
 terrarium_logto_instance_profile: terrarium
 terrarium_logto_core_port: 3001
 terrarium_logto_admin_port: 3002
+terrarium_logto_admin_email: "{{ terrarium_email }}"
+terrarium_logto_admin_username: terrarium_admin
 terrarium_docker_registry_config_path: /root/.docker/config.json
 terrarium_docker_hardened_images: auto
 terrarium_docker_hardened_image_mirrors: true

ansible/roles/idp_logto/tasks/main.yml

@@ -110,7 +110,11 @@
         'set -eu;
         umask 077;
         [ -f /etc/terrarium/secrets/logto_postgres_password ] || tr -dc "A-Za-z0-9" </dev/urandom | head -c 48 > /etc/terrarium/secrets/logto_postgres_password;
-        [ -f /etc/terrarium/secrets/logto_secret_vault_kek ] || openssl rand -base64 32 > /etc/terrarium/secrets/logto_secret_vault_kek'
+        [ -f /etc/terrarium/secrets/logto_secret_vault_kek ] || openssl rand -base64 32 > /etc/terrarium/secrets/logto_secret_vault_kek;
+        if [ ! -f /etc/terrarium/secrets/logto_admin_password ]; then
+          pw="$(tr -dc "A-Z" </dev/urandom | head -c 1)$(tr -dc "a-z" </dev/urandom | head -c 1)$(tr -dc "0-9" </dev/urandom | head -c 1)!$(tr -dc "A-Za-z0-9" </dev/urandom | head -c 28)";
+          printf "%s" "$pw" > /etc/terrarium/secrets/logto_admin_password;
+        fi'
       changed_when: false
       no_log: true
 
@@ -188,6 +192,12 @@
       changed_when: false
       no_log: true
 
+    - name: Read Logto local admin password from system instance
+      ansible.builtin.command: "/snap/bin/lxc exec {{ terrarium_logto_instance_name }} -- cat /etc/terrarium/secrets/logto_admin_password"
+      register: terrarium_logto_admin_password_raw
+      changed_when: false
+      no_log: true
+
     - name: Create local Logto staging directory
       ansible.builtin.file:
         path: "{{ terrarium_logto_stage_dir }}"
@@ -265,7 +275,7 @@
     - name: Run Logto reconciliation
       ansible.builtin.command: /usr/local/bin/terrariumctl idp sync
       environment:
-        TERRARIUM_LOGTO_ADMIN_PASSWORD: "{{ terrarium_root_password_plaintext | default('', true) }}"
+        TERRARIUM_LOGTO_ADMIN_PASSWORD: "{{ terrarium_logto_admin_password_raw.stdout }}"
       register: terrarium_logto_sync
       until: terrarium_logto_sync.rc == 0
       retries: 6

ansible/site.yml

@@ -65,6 +65,8 @@
     terrarium_logto_stage_dir: "{{ terrarium_state_dir }}/logto-container"
     terrarium_logto_core_port: 3001
     terrarium_logto_admin_port: 3002
+    terrarium_logto_admin_email: "{{ terrarium_email }}"
+    terrarium_logto_admin_username: terrarium_admin
     terrarium_local_idp_outputs_path: ""
     terrarium_local_idp_outputs_path_default: /etc/terrarium/idp-apps.json
     terrarium_zitadel_outputs_path: /etc/terrarium/zitadel-apps.json
@@ -139,6 +141,8 @@
       terrarium_logto_stage_dir: "{{ terrarium_logto_stage_dir }}"
       terrarium_logto_core_port: "{{ terrarium_logto_core_port }}"
       terrarium_logto_admin_port: "{{ terrarium_logto_admin_port }}"
+      terrarium_logto_admin_email: "{{ terrarium_logto_admin_email }}"
+      terrarium_logto_admin_username: "{{ terrarium_logto_admin_username }}"
       terrarium_local_idp_outputs_path: "{{ terrarium_local_idp_outputs_path_effective | default(terrarium_local_idp_outputs_path) }}"
       terrarium_zitadel_outputs_path: "{{ terrarium_zitadel_outputs_path_effective | default(terrarium_zitadel_outputs_path) }}"
       terrarium_oauth2_proxy_image: "{{ terrarium_oauth2_proxy_image_effective | default(terrarium_oauth2_proxy_image_fallback) }}"
@@ -390,6 +394,8 @@
               'terrarium_logto_stage_dir': terrarium_logto_stage_dir,
               'terrarium_logto_core_port': terrarium_logto_core_port,
               'terrarium_logto_admin_port': terrarium_logto_admin_port,
+              'terrarium_logto_admin_email': terrarium_logto_admin_email,
+              'terrarium_logto_admin_username': terrarium_logto_admin_username,
               'terrarium_logto_app_image': terrarium_logto_app_image_effective,
               'terrarium_logto_postgres_image': terrarium_logto_postgres_image_effective,
               'terrarium_local_idp_discovery_url': terrarium_local_idp_discovery_url_effective

docs/getting-started/domains-and-auth.md

@@ -166,14 +166,16 @@ If you omit `--idp-provider` in local mode, Terrarium keeps the compatibility de
 Defaults:
 - Auth domain: `auth.<domain>` or `auth.<dashed-public-ip>.traefik.me`
 - Admin group: `terrarium-admins`
+- Local Logto admin email: `terrarium_email`
+- Local Logto admin username: `terrarium_admin`
 
 With local ZITADEL, Terrarium will automatically:
 - Provision the necessary management role.
 - Grant that role to the bootstrap admin user.
 - Emit a flat `groups` claim for `oauth2-proxy` and LXD to read.
 - Keep route-auth callback URLs in the managed ZITADEL app up to date when you run `terrariumctl proxy sync`.
 
-With local Logto, Terrarium also uses the same `auth.<domain>` public endpoint, but it runs Logto plus Postgres in the managed IDP system instance. Bootstrap is unattended: Terrarium seeds the Logto database, creates the Terrarium OAuth clients, creates the admin role, assigns it to the bootstrap admin email when that user exists, and writes the local client outputs consumed by oauth2-proxy, LXD, and route auth. Logto defaults to the `roles` claim and `openid profile email roles` scopes for both management and LXD unless you override the claim/scope flags.
+With local Logto, Terrarium also uses the same `auth.<domain>` public endpoint, but it runs Logto plus Postgres in the managed IDP system instance. Bootstrap is unattended: Terrarium seeds the Logto database, creates the Terrarium OAuth clients, creates the admin role, assigns it to the bootstrap admin email when that user exists, and writes the local client outputs consumed by oauth2-proxy, LXD, and route auth. The bootstrap email defaults to your Terrarium contact email and the username defaults to `terrarium_admin`; override them with `--logto-admin-email` and `--logto-admin-username`. Logto defaults to the `roles` claim and `openid profile email roles` scopes for both management and LXD unless you override the claim/scope flags.
 
 ### Mode 2: External OIDC (`--idp oidc`)
 

docs/getting-started/installation.md

@@ -73,7 +73,7 @@ Use local Logto instead:
 terrariumctl install --idp local --idp-provider logto
 ```
 
-Local Logto is heavier than local ZITADEL: Terrarium runs Logto and Postgres in the managed IDP system instance, seeds Logto unattended, and provisions the Terrarium OIDC clients during `terrariumctl idp sync`.
+Local Logto is heavier than local ZITADEL: Terrarium runs Logto and Postgres in the managed IDP system instance, seeds Logto unattended, and provisions the Terrarium OIDC clients during `terrariumctl idp sync`. The bootstrap admin email defaults to your Terrarium contact email and the username defaults to `terrarium_admin`; override them with `--logto-admin-email` and `--logto-admin-username`.
 
 Use external generic OIDC, preserving the existing `groups` claim and `openid profile email` scope defaults:
 
@@ -126,6 +126,7 @@ The installer will guide you through:
 - IDP provider:
   - `zitadel` is the compatibility default for local installs
   - `logto` selects local Logto or external Logto/Logto Cloud defaults
+- Local Logto bootstrap email and username when `--idp-provider logto` is selected.
 - Storage mode and storage source.
 - Optional S3 archive backups.
 - Optional syncoid replication.

docs/reference/terrariumctl.md

@@ -163,7 +163,7 @@ trm image delete golden-web
 | `--non-interactive` | none | no | interactive mode if omitted | Disables prompts and requires all needed config through flags. |
 | `--yes` | none | no | prompt before destructive actions | Auto-confirms destructive or confirmation prompts. |
 | `--ref` | git branch or tag | no | `main` when invoking `terrariumctl` directly; release-selected tag when run through `install.sh` | Installs a specific Terrarium release tag, or builds from a branch-like source ref such as `main`. |
-| `--email` | email address | yes in non-interactive mode; no in interactive mode | prompted in interactive mode | Sets the Terrarium contact/admin email and default ZITADEL bootstrap admin email. |
+| `--email` | email address | yes in non-interactive mode; no in interactive mode | prompted in interactive mode | Sets the Terrarium contact/admin email and the default local-provider bootstrap admin email. |
 | `--acme-email` | email address | no | falls back to `--email` | Sets the ACME account identity for Traefik and LXD certificate automation. |
 | `--domain` | root domain | no | service domains default to `<service>.<dashed-public-ip>.traefik.me` when omitted | Sets the root domain used to derive service subdomains. |
 | `--manage-domain` | domain | no | `manage.<domain>` when `--domain` is set, otherwise `manage.<dashed-public-ip>.traefik.me` | Overrides the Cockpit domain. |
@@ -185,6 +185,8 @@ trm image delete golden-web
 | `--lxd-oidc-groups-claim` | claim name | no | follows provider default unless set | Overrides the LXD OIDC groups/roles claim. |
 | `--lxd-oidc-scopes` | space-separated scopes | no | follows provider default unless set | Overrides the LXD OIDC scopes. |
 | `--zitadel-admin-email` | email address | no | falls back to `--email` | Sets the initial admin email for self-hosted ZITADEL. |
+| `--logto-admin-email` | email address | no | falls back to `--email` for local Logto | Sets the bootstrap admin email for self-hosted Logto. |
+| `--logto-admin-username` | username | no | `terrarium_admin` for local Logto | Sets the bootstrap admin username for self-hosted Logto. Whitespace and control characters are rejected. |
 | `--generate-root-pwd` | none | yes in non-interactive mode when root has no usable local password unless `--root-pwd-file` is passed; no otherwise | none | Generates a strong Cockpit root password and saves it to `/etc/terrarium/secrets/cockpit_root_password` with root-only permissions. |
 | `--root-pwd-file` | path | yes in non-interactive mode when root has no usable local password unless `--generate-root-pwd` is passed; no otherwise | none | Reads the Cockpit root password from a local file. |
 | `--storage-mode` | `disk`, `partition`, or `file` | yes in non-interactive mode; no in interactive mode | prompted or auto-selected in interactive mode | Selects how the LXD ZFS pool is created. |
@@ -675,6 +677,7 @@ Behavior:
 | `--email` | email address | no | existing configured value | Updates the Terrarium contact/admin email. |
 | `--acme-email` | email address | no | existing configured value or falls back to `--email` | Updates the ACME account email. |
 | `--zitadel-admin-email` | email address | no | existing configured value or falls back to `--email` | Updates the self-hosted ZITADEL bootstrap admin email. |
+| `--logto-admin-email` | email address | no | existing configured value or falls back to `--email` when local Logto is selected | Updates the self-hosted Logto bootstrap admin email. |
 
 ## set idp
 
@@ -697,6 +700,8 @@ Behavior:
 | `--lxd-oidc-scopes` | space-separated scopes | no | follows provider default unless set | Overrides the LXD OIDC scopes. |
 | `--local-idp-outputs-path` | path | no | `/etc/terrarium/zitadel-apps.json` compatibility path | Overrides where local provider client outputs are read/written. |
 | `--zitadel-admin-email` | email address | no | existing configured value or `--email` | Updates the ZITADEL bootstrap admin email when mode is `local`. |
+| `--logto-admin-email` | email address | no | existing configured value or `--email` when provider is `logto` and mode is `local` | Updates the Logto bootstrap admin email when mode is `local`. |
+| `--logto-admin-username` | username | no | existing configured value or `terrarium_admin` when provider is `logto` and mode is `local` | Updates the Logto bootstrap admin username when mode is `local`. Whitespace and control characters are rejected. |
 
 External OIDC notes:
 
@@ -715,6 +720,7 @@ Local provider notes:
 - Local ZITADEL remains the default when mode is `local` and no provider is set. External OIDC remains generic when no provider is set.
 - Local ZITADEL runs in the `terrarium-idp` LXD system instance, so its data is part of the LXD/ZFS backup set instead of host Docker state.
 - Local Logto also runs in the managed `terrarium-idp` system instance. It starts Logto plus Postgres through `terrarium-logto.service`, seeds the database unattended, and provisions Terrarium clients during `terrariumctl idp sync`.
+- Local Logto bootstrap defaults use `terrarium_email` for `terrarium_logto_admin_email` and `terrarium_admin` for `terrarium_logto_admin_username`; override them with `--logto-admin-email` and `--logto-admin-username` during install or `terrariumctl set idp local --provider logto`.
 - Terrarium auto-provisions a management role named after `terrarium_admin_group`, defaulting to `terrarium-admins`.
 - The bootstrap admin is granted that role automatically when the selected provider can resolve that user.
 - ZITADEL flattens Terrarium role assignments into a `groups` claim. Logto uses its `roles` claim and `openid profile email roles` scopes by default.

scripts/ctl/completion.test.ts

@@ -50,6 +50,8 @@ describe("terrariumctl completion", () => {
     expect(script).toContain("--profile --disk --memory --cpu --requirements --playbook --role --docker-compose --cloud-init --proxy");
     expect(script).toContain("--ref --skip-reconfigure --non-interactive");
     expect(script).toContain("--skip-reconfigure");
+    expect(script).toContain("--logto-admin-email");
+    expect(script).toContain("--logto-admin-username");
     expect(script).toContain("--storage-source");
     expect(script).toContain("local oidc");
     expect(script).toContain("provider");

scripts/ctl/completion.ts

@@ -59,6 +59,7 @@ const optionGroups: Record<string, string[]> = {
     "--proxy-domain",
     "--lxd-domain",
     "--idp",
+    "--idp-provider",
     "--admin-group",
     "--oidc",
     "--oidc-client",
@@ -69,6 +70,8 @@ const optionGroups: Record<string, string[]> = {
     "--lxd-oidc-secret-file",
     "--auth-domain",
     "--zitadel-admin-email",
+    "--logto-admin-email",
+    "--logto-admin-username",
     "--generate-root-pwd",
     "--root-pwd-file",
     "--storage-mode",
@@ -147,6 +150,10 @@ const optionGroups: Record<string, string[]> = {
     "--email",
     "--acme-email",
     "--zitadel-admin-email",
+    "--logto-admin-email",
+    "--logto-admin-username",
+    "--provider",
+    "--idp-provider",
     "--admin-group",
     "--oidc",
     "--oidc-client",

scripts/ctl/config.test.ts

@@ -58,6 +58,8 @@ describe("terrariumctl config reconciliation", () => {
 
     expect(ctlSource).toContain('.option("--provider <provider>"');
     expect(ctlSource).toContain('.option("--idp-provider <provider>"');
+    expect(ctlSource).toContain('.option("--logto-admin-email <email>"');
+    expect(ctlSource).toContain('.option("--logto-admin-username <username>"');
     expect(configSource).toContain('provider: cliOption(rawOptions, "provider", ["idpProvider", "idp-provider"])');
   });
 
@@ -68,7 +70,9 @@ describe("terrariumctl config reconciliation", () => {
       "oidc-scopes": "openid profile email roles",
       "lxd-oidc-groups-claim": "organization_roles",
       "lxd-oidc-scopes": "openid email organizations",
-      "local-idp-outputs-path": "/run/terrarium/idp-apps.json"
+      "local-idp-outputs-path": "/run/terrarium/idp-apps.json",
+      "logto-admin-email": "owner@example.test",
+      "logto-admin-username": "owner_admin"
     });
 
     expect(parsed.idp.provider).toBe("logto");
@@ -77,6 +81,16 @@ describe("terrariumctl config reconciliation", () => {
     expect(parsed.idp.lxdOidcGroupsClaim).toBe("organization_roles");
     expect(parsed.idp.lxdOidcScopes).toBe("openid email organizations");
     expect(parsed.idp.localIdpOutputsPath).toBe("/run/terrarium/idp-apps.json");
+    expect(parsed.idp.logtoAdminEmail).toBe("owner@example.test");
+    expect(parsed.idp.logtoAdminUsername).toBe("owner_admin");
+  });
+
+  test("parses Logto admin email set email flag", () => {
+    const parsed = parseSetCommandOptions({
+      "logto-admin-email": "owner@example.test"
+    });
+
+    expect(parsed.emails.logtoAdminEmail).toBe("owner@example.test");
   });
 
   test("syncs local IDP outputs before proxy config convergence finishes", async () => {
@@ -231,6 +245,37 @@ describe("terrariumctl config reconciliation", () => {
     expect(lxdOidcScopes(config)).toBe("openid lxd");
   });
 
+  test("defaults local Logto admin config when switching to local Logto", () => {
+    const config: Record<string, unknown> = {
+      terrarium_public_ip: "203.0.113.10",
+      terrarium_root_domain: "example.test",
+      terrarium_email: "admin@example.test"
+    };
+
+    applySetIdpConfig(config, { mode: "local", provider: "logto" });
+
+    expect(config.terrarium_logto_admin_email).toBe("admin@example.test");
+    expect(config.terrarium_logto_admin_username).toBe("terrarium_admin");
+  });
+
+  test("persists explicit local Logto admin config", () => {
+    const config: Record<string, unknown> = {
+      terrarium_public_ip: "203.0.113.10",
+      terrarium_root_domain: "example.test",
+      terrarium_email: "admin@example.test"
+    };
+
+    applySetIdpConfig(config, {
+      mode: "local",
+      provider: "logto",
+      logtoAdminEmail: " owner@example.test ",
+      logtoAdminUsername: " owner_admin "
+    });
+
+    expect(config.terrarium_logto_admin_email).toBe("owner@example.test");
+    expect(config.terrarium_logto_admin_username).toBe("owner_admin");
+  });
+
   test("skips ZITADEL output stabilization for local Logto provider", async () => {
     const calls: string[] = [];