Is OpenConnect --key-password your VPN account password?

Read the option name literally. It names a key, and the confusion starts when the file being unlocked is mistaken for the account being authenticated. Paste the account password into that option and the client will try to open a key file with it, which fails for reasons that have nothing to do with the VPN login.

The confusing part is that a single connection can legitimately need both secrets. Client-certificate authentication may require an encrypted key, and the same gateway may still run a user authentication exchange after the certificate is accepted. Neither secret satisfies the other stage, and a failure in one looks a lot like a failure in the other from the outside.

Two secrets, two different jobs

Read the roles as file access versus network admission. The key password decrypts the PEM private key named by --sslkey so the TLS client certificate can be presented. That decryption happens locally, inside the client process, and the passphrase itself never travels to the gateway. What the gateway sees is the certificate and a signature made with the key. The OpenConnect manual keeps --key-password next to --certificate and --sslkey, and on builds that can use a key held in a TPM the same option carries the storage root key password instead.

The account password is different in kind. It goes into the authentication exchange: a username and password form, a token, a SAML round trip, or some combination the gateway advertises. Some deployments do not ask for it at all when the certificate is the only factor, and some ask for it even after a certificate, because the certificate proves the device while the account proves the person.

Mixing the two produces misleading errors. A gateway rejecting a login usually reports an authentication failure, while a wrong key passphrase usually fails earlier, when the TLS layer cannot read the key file. Those are different stages with different fixes, and the names are similar enough that people swap them and then chase the wrong log. Note which prompt appeared before you change any setting, because the wording of the prompt is the cheapest diagnostic you have.

When the key password is actually needed

The option is only meaningful when there is an encrypted key to unlock. If you connect with a username and password and no client certificate, --key-password has nothing to act on, and including it changes nothing. If you connect with --certificate and --sslkey, the key file's own format decides whether a passphrase is requested at all.

Both secrets in one command is common in managed environments: a device certificate in an encrypted key, plus a per-user sign-in. The right sequence is to let the client prompt for the key passphrase locally, complete the certificate handshake, and then handle the gateway's account prompt separately. Trying to pre-fill both through one reused script is where the mix-up usually starts.

A useful diagnostic is to look at when the failure happens. If the client stops before any network authentication begins, suspect the key file, its format, or the passphrase. If the TLS session is established and the gateway then rejects the user, the key did its job and the account exchange is the problem.

Keeping both secrets out of shell history

Command-line arguments are readable by other local users through the process table and are frequently captured in shell history, scripts, and support transcripts. OpenConnect can read the account password from standard input with --passwd-on-stdin, and the key passphrase can come from an interactive prompt or an agent rather than an argument. Neither mechanism makes the secret safe by itself, but both keep it out of the most exposed places.

Files deserve the same care. A script that writes a passphrase to a temporary file should create it with restrictive permissions, delete it on exit, and avoid world-readable directories. A passphrase that survives the session in a temporary directory is a copy you forgot to make. Environment variables are visible to child processes and often end up echoed by debug tooling, so they are not a free upgrade over arguments.

Diagnostic output is the quiet leak. Client logs at higher verbosity can show request bodies or option values, and a copied terminal transcript is easy to paste into a ticket, so read the output before sharing it.

A dead desktop button is a different fault

A desktop VPN entry that shows a spinner and then nothing is usually not an authentication problem at all. The button belongs to a network manager, a vendor applet, or a plugin that launches OpenConnect on your behalf, and a missing component or unreadable profile can produce exactly that symptom. Find which process the button starts and read its error before touching credentials.

It is tempting to relax certificate verification or disable a check when the GUI refuses to connect. That converts a client-integration fault into a security downgrade and rarely fixes the launch problem. Keep server verification intact, confirm the profile points at the intended gateway, and check that the helper the GUI expects is actually installed.

A short checklist separates the cases. A local failure before any packet leaves points at the key or the client install. A gateway rejection after the TLS session points at the account exchange. A button that never launches the client points at the desktop integration. Three different faults, one of which is a password you were about to paste in the wrong box.