Authentication Problems

Overview

Authentication problems in NetStacks happen at distinct layers, and the layer you are in determines the fix. Most failures fall into one of three buckets: unlocking the encrypted credential vault, authenticating to a managed device over SSH or Telnet, or (when you run the optional Controller) logging into the Controller via LDAP, OIDC, or a JWT API session.

Where authentication can fail

• Vault unlock -- The encrypted credential vault is locked and the master password (or biometric unlock) is not accepted, so stored credentials cannot be read.
• Biometric unlock -- On macOS, Touch ID is unavailable, not enrolled, cancelled, or the stored password no longer matches the vault.
• Device authentication -- The target device rejects the password or SSH key presented during the SSH/Telnet handshake.
• Controller login (LDAP / OIDC) -- The Controller cannot bind to LDAP/Active Directory or complete the OIDC single sign-on flow.
• JWT / API session -- A Controller API request is rejected because the JSON Web Token has expired or is otherwise invalid.

How It Works

Understanding the flow from unlocking the vault to authenticating to a device makes it easy to isolate which stage is failing.

Authentication flow

1. Vault unlock -- On the standalone Terminal you unlock the local credential vault with your master password (or Touch ID on macOS). The vault is encrypted with AES-256-GCM and the key is derived from your password with Argon2id, so the password is never stored in plaintext.
2. Credential retrieval -- When you open a device connection, NetStacks reads the assigned credential (password, or SSH key with an optional passphrase) from the unlocked vault.
3. Device authentication -- NetStacks performs the SSH or Telnet handshake. For password auth over SSH it tries keyboard-interactive first (many network devices require it) and then plain password auth; for key auth it presents the private key.
4. Controller login (optional) -- If you use the Controller, you first authenticate to it with local credentials, an LDAP bind, or an OIDC redirect. On success the Controller issues a JWT used for subsequent API requests.

Vault Unlock Failures

The credential vault must be unlocked before NetStacks can read any stored password, SSH key, or token. On the standalone Terminal the vault lives entirely on your local machine; there is no account recovery and no server-side reset.

If the master password is rejected

• Re-enter the password carefully. Decryption either succeeds or fails as a whole -- a wrong password produces a generic Decryption failed - wrong password or corrupted data result rather than a hint, by design.
• Confirm you are unlocking the vault you think you are. If you moved or restored the vault data, the master password is whatever it was when that data was last encrypted.
• There is no "forgot password" for the local vault. The master password is the only key; if it is lost, the encrypted credentials cannot be recovered and the vault must be wiped and re-created.

If the vault appears locked unexpectedly

• The vault locks when you lock it explicitly or when the app is restarted. Simply unlock it again with your master password.
• After changing the master password, every stored secret is re-encrypted under the new key in a single operation. Use the new password to unlock from then on.

Biometric (Touch ID) Unlock

On macOS, NetStacks can unlock the vault with Touch ID instead of typing the master password each time. When you enable it, NetStacks verifies your master password once and stores it in the macOS Keychain; later unlocks present a Touch ID prompt and feed the stored password into the normal vault-unlock flow. Biometric unlock is macOS-only -- on other platforms it is reported as unsupported.

Common biometric failure modes

Touch ID is unavailable / not enrolled on the Mac

The strict biometric policy requires a fingerprint enrolled in macOS. If no fingerprint is enrolled, the prompt cannot run. Enroll Touch ID in macOS System Settings, then retry, or unlock with your master password instead.

Vault biometric not enrolled in NetStacks

If you never enabled Touch ID for the vault (or the Keychain entry was removed externally), the status reports enrolled: false and biometric unlock returns a not-enrolled error. Re-enable Touch ID from the vault settings -- you will be asked for your master password to re-store it.

Prompt cancelled

Dismissing or cancelling the Touch ID prompt aborts the unlock. Just unlock with your master password, which always remains available as the recovery path -- the Touch ID prompt itself does not offer a system-password fallback.

Stored password no longer matches the vault

If you changed the master password elsewhere, the password saved in the Keychain is now stale. The biometric unlock self-heals: it deletes the stale Keychain entry and turns the toggle off, so the next unlock falls back to manual password entry. Re-enable Touch ID afterward to re-enroll.

Device Authentication (SSH / Telnet)

Once the vault is unlocked, NetStacks uses the credential assigned to a device to authenticate over SSH or Telnet. NetStacks supports two SSH credential types: a password, or an SSH private key with an optional passphrase.

If a device rejects the password

• Verify the username and password are correct for that device.
• Confirm the credential actually assigned to the device is the one you expect -- an old or shared credential is a common cause.
• For SSH password auth, NetStacks tries keyboard-interactive first and then plain password auth. Some hardened devices accept only one of these; ensure the device permits at least one password method for your user.

If a device rejects the SSH key

• Confirm the matching public key is installed on the device for the login user.
• Verify the private-key file path is correct and that NetStacks can read it.
• If the key is passphrase-protected, make sure the passphrase stored with the credential is correct -- a wrong or missing passphrase makes the key unusable.
• Some legacy devices reject newer key algorithms. If a modern key type is rejected, try a key type the device is known to accept.

Controller Login (LDAP / OIDC / JWT)

This section applies only when you deploy the optional Controller. The standalone Terminal does not use LDAP, OIDC, or JWT.

LDAP / Active Directory

1. Verify the LDAP server is reachable from the Controller host.
2. Check the Bind DN and Bind Password in the Controller's auth settings.
3. Confirm the user search base DN includes the target user's OU.
4. Verify the user filter matches the login attribute -- Active Directory uses sAMAccountName while many OpenLDAP setups use uid.
5. Test with ldapsearch from the Controller host to isolate LDAP from NetStacks configuration.
6. If using LDAPS (port 636), verify the TLS certificate is trusted.

OIDC / single sign-on

1. Ensure the redirect URI registered with the OIDC provider matches the Controller callback URL exactly (protocol, host, port, and path).
2. Confirm the client ID and client secret are correct.
3. Check that required scopes (openid, profile, email) are configured.
4. Verify the provider's discovery endpoint is reachable from the Controller.
5. Confirm system clocks are in sync -- token validation is time-sensitive.

JWT / API sessions

• A 401 usually means the JWT is expired or invalid -- re-authenticate or let the client refresh the token.
• Clock drift between the API client and Controller can cause spurious expiry; keep both in sync with NTP.

Code Examples

SSH key permission check (on the machine running NetStacks)

# Verify SSH key file permissions
ls -la ~/.ssh/
# Expected:
# drwx------  .ssh/           (700)
# -rw-------  id_ed25519      (600)
# -rw-r--r--  id_ed25519.pub  (644)

# Fix permissions if too open
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Sanity-check the key against the device directly
ssh -i ~/.ssh/id_ed25519 -o PreferredAuthentications=publickey [email protected]

Vault biometric status (standalone Terminal local API)

# Query whether biometric unlock is supported / enrolled / enabled.
# This does NOT trigger a Touch ID prompt.
curl -s http://127.0.0.1:PORT/vault/biometric/status

# Example response:
{
  "supported": true,   // biometric available on this build (macOS)
  "enrolled": true,    // a Keychain entry exists
  "enabled": true      // toggle is on AND a Keychain entry exists
}

LDAP bind test (Controller only)

# Test an LDAP bind from the Controller host
ldapsearch -x -H ldap://ldap.example.com:389 \
  -D "cn=netstacks-svc,ou=ServiceAccounts,dc=example,dc=com" \
  -W \
  -b "ou=Users,dc=example,dc=com" \
  "(sAMAccountName=jdoe)" dn

# Test an LDAPS (TLS) bind
ldapsearch -x -H ldaps://ldap.example.com:636 \
  -D "cn=netstacks-svc,ou=ServiceAccounts,dc=example,dc=com" \
  -W \
  -b "ou=Users,dc=example,dc=com" \
  "(uid=jdoe)" dn

JWT inspection and API auth test (Controller only)

# Decode a JWT payload (second segment) without verifying it
echo "eyJhbGciOiJIUzI1NiIs..." | cut -d. -f2 | base64 -d 2>/dev/null | jq .

# Check when the token expires
date -d @1709859600

# Test an authenticated API call
curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer <your-jwt-token>" \
  https://controller.example.com/api/v1/users/me
# 200 = OK, 401 = invalid/expired token, 403 = insufficient permissions

Q&A

Q: I forgot my vault master password -- how do I recover it?

A: On the standalone Terminal you cannot. The master password is the only key that decrypts the vault (AES-256-GCM with an Argon2id-derived key), and it is never stored in plaintext. If it is lost, the encrypted credentials are unrecoverable -- the only path forward is to wipe the vault and re-create your credentials. Record the master password somewhere safe.

Q: Touch ID stopped unlocking my vault on macOS. Why?

A: The most common causes are: Touch ID is no longer enrolled in macOS (enroll a fingerprint in System Settings), biometric unlock was never enabled or its Keychain entry was removed (re-enable it in vault settings with your master password), the prompt was cancelled, or the master password was changed elsewhere so the stored password is stale. In the stale-password case NetStacks automatically removes the saved entry and turns the toggle off, so the next unlock falls back to your master password -- re-enable Touch ID afterward.

Q: Is biometric unlock available on Windows or Linux?

A: No. Biometric vault unlock is implemented only on macOS (Touch ID via the system biometric prompt). On other platforms it is reported as unsupported, and you unlock the vault with your master password.

Q: How do I fix "Permission denied (publickey)" to a device?

A: The device rejected the SSH key. Confirm the matching public key is installed on the device for that user, the private-key path is correct and readable, and -- if the key is passphrase-protected -- the passphrase stored with the credential is correct. If a modern key algorithm is rejected by a legacy device, try a key type the device accepts.

Q: SSH password auth fails even though the password is right -- why?

A: For SSH, NetStacks tries keyboard-interactive authentication first (many network devices such as some Cisco and Arista platforms require it) and then falls back to plain password auth. If the device permits neither method for your user, or only permits public-key auth, password authentication will fail regardless of the password being correct. Confirm which auth methods the device allows.

Q: Why does LDAP login fail on the Controller?

A: LDAP failures are usually an incorrect Bind DN or password, a search base DN that does not include the user's OU, a user filter that targets the wrong attribute (uid vs sAMAccountName), or network connectivity between the Controller and the directory. Run ldapsearchfrom the Controller host to determine whether the problem is the directory or the NetStacks configuration. This applies only if you deploy the Controller.

Q: Why is my Controller JWT rejected?

A: Typical causes are an expired token (check the exp claim), clock drift between the client and Controller (validation is time-sensitive), a token issued by a different Controller instance, or a rotated signing key. Re-authenticate or let the client refresh the token, and keep clocks in sync with NTP.

Troubleshooting

Use this lookup table to map a symptom to its likely cause and fix.

Related Features

• Credentials: Vault -- How the encrypted vault works, master password, and locking/unlocking
• Credentials: Personal Vaults -- Per-user vaults and where credentials are isolated
• Credentials: SSH, Passwords & Keys -- Storing device passwords and SSH keys with passphrases
• Credentials: Certificates -- Certificate handling and CA management
• Terminal: Connecting -- Opening SSH and Telnet sessions to devices
• Admin: Authentication -- Configure Controller LDAP, OIDC, and local authentication
• API: Authentication -- Controller API tokens and the JWT refresh flow
• Troubleshooting: Connection Issues -- When authentication succeeds but the connection itself fails