Skip to content

Passwords from a command

Some servers take a short-lived token instead of a fixed password: an IAM token on Amazon RDS or Cloud SQL, an Entra token on Azure, a password from Vault. Alcuin can run the command that prints it, each time it connects.

Set it up

Section titled “Set it up”

  1. Open the connection’s form and set Authentication to Password from command.

  2. Fill in the fields that appear:

    Field What it takes
    Command The command, which prints the password on its first line
    Variables NAME=value pairs for the command, such as AWS_PROFILE=prod AWS_REGION=eu-west-1
    Reuse the password for Minutes to reuse what the command printed, from 1 to 720. The default is 10.

  3. Click Test the command. The first time, Alcuin asks you to approve it.

  4. When it works, Alcuin says how many lines the command printed and how long the password is, such as ✓ It printed 1 line and · 1,024 characters, taken as the password. It never shows the password itself.

  5. Click Test connection, then Save.

Under Command, the Examples row offers AWS RDS, Cloud SQL, Entra ID and Vault. Choosing one shows that command as the field’s placeholder; copy it in and change the host, user and region to yours. When a command needs stronger encryption than the connection has, a hint under it names the Encryption setting it needs, and the CA file where there is one. It stays until you choose Required, verify server or Required, verify certificate; Required alone doesn’t check the server, so the hint stays.

Approve the command once

Section titled “Approve the command once”

Before a command runs for the first time, Alcuin asks in a system dialog: Run a command to get the password for and the connection’s name. The dialog shows the command exactly as it will run, its variables, the server the password goes to and the connection’s encryption. Don’t run is the default; click Run the command to approve it.

Alcuin remembers the approval for that connection and asks again when:

  • the command or its variables change,
  • the server changes: its host, port, user or SSH tunnel,
  • the encryption is weakened, for example from Required, verify server to Required.

If you choose Don’t run, the connect fails with You chose not to run the password command, so Alcuin did not connect. Alcuin does not ask again until you change the command, its variables or the server, or restart Alcuin.

A command you approve while testing a new connection stays approved when you save it in the same launch, so you are not asked twice.

What runs

Section titled “What runs”

Alcuin runs the command as you, on this computer, without a shell.

  • Words are split the way a shell splits them, and single quotes, double quotes and backslashes work as in a terminal. A word starting ~/ is in your home folder.
  • Pipelines, redirects, variables and globs do not work. A command with |, &, ;, <, >, (, ), $, a backtick, *, ?, [, { or a # comment is refused before it runs. Put that logic in a script and give the script’s path as the command.
  • The command sees your login shell’s environment, as a terminal would, read once per launch, plus the variables you set. So a tool installed with Homebrew is found on your usual PATH.
  • It gets no input: anything that waits for you to type reads end of file.
  • It has 30 seconds to finish.
  • Sign-in commands, such as aws sso login, az login, gcloud auth login or vault login, are refused: they open a browser or ask for input. Run them in a terminal first.

Alcuin takes the first line of what the command prints, without surrounding spaces, as the password. Further lines are ignored.

When it runs, and what Alcuin keeps

Section titled “When it runs, and what Alcuin keeps”

The command runs when the connection opens and when it reconnects. A connection opens several sessions to the server, and they share one run: Alcuin reuses the output for as long as Reuse the password for says. Test the command always runs it afresh.

Keep the reuse time shorter than the token’s life. RDS tokens last 15 minutes, which is why the default is 10.

  • The approval is kept with the connection’s saved secrets: a fingerprint of the command and its variables, the server it is for, and the encryption you approved.
  • The output is kept in memory only, for the reuse time. It is never written to disk or to the log.
  • For a connection that is not saved, the output is not reused and the approval lasts until you quit.

Recipes

Section titled “Recipes”

Sign in to the provider’s tool in a terminal before you test.

Provider Command
Amazon RDS and Aurora aws rds generate-db-auth-token --hostname <endpoint> --port 5432 --username <user> --region <region>
Azure Database for PostgreSQL az account get-access-token --resource-type oss-rdbms --query accessToken --output tsv
Cloud SQL gcloud sql generate-login-token
HashiCorp Vault vault read -field=password database/static-creds/<role>

Set Variables for what the tool would otherwise take from your shell, such as AWS_PROFILE=prod, or VAULT_ADDR=https://vault.example.com.

A server may ask for the token in clear text. Alcuin sends a password that way only over TLS that checks the server’s certificate, through an SSH tunnel, or to this machine. So for RDS, Azure and a direct Cloud SQL connection, set Encryption to Required, verify server, or Required, verify certificate with the provider’s CA. Cloud providers has the full recipe for each, and TLS and sslmode explains the settings.

If the command fails

Section titled “If the command fails”

Test the command, or Test connection, shows the error and the last lines the command wrote to its error output. Nothing was sent to the server. Run the command in a terminal and read what it says: it usually needs you to sign in first. The password command exited with code 1 has each message and its fix.