Identities and groups

Which to use

• An identity is a credential with a name: “Deploy key”, “Break-glass admin”. Each host chooses to use it. Good when the same login is spread across hosts in different groups, or when you rotate a key and want every host that uses it to follow.
• A group credential belongs to a group: every host filed under that group inherits it. Good when a whole group of machines shares one login, or sits behind the same jump host.

You can use both. The rules below decide which one wins.

How MangoSSH picks a credential

For every connect, MangoSSH looks in three places, most specific first:

The host's own value always wins. An identity or group never replaces a password or key someone set on one machine on purpose. The test is all or nothing: a host with any password, key passphrase or key file of its own is treated as fully configured, and neither the identity nor the group is used for it.

Field by field:

The same rules apply everywhere a host is used: a normal connect, a hop through a jump host, and Scripts.

Identities

Create an identity

1. Open Settings → Identities and click Add identity. Type a name and click Add. Its editor opens.

2. Fill in what it should supply:

   • Username.
   • Authentication: Password, SSH key + passphrase, SSH key only, SSH agent, PKCS#11 / smartcard, Windows Hello / Secure Enclave, or Leave to the host to keep each host's own method.
   • Key file and Certificate: paths on this computer, if the method uses them.
   • Notes: whose credential this is and when it was last rotated. MangoSSH never reads it.

3. Use Set next to the password or the key passphrase to store the secret. It goes into this computer's OS keychain, not into the identity record.

4. Click Save. The list row now summarises what the identity supplies, with badges for any stored secret.

Identities are kept encrypted alongside your local vault. If the vault is locked, identities cannot be edited, and hosts connect as if they had no identity until you unlock it.

Attach it to a host

For the identity to apply, the host must have no credential of its own. For a new host that is automatic. For an existing one, clear it first:

1. Edit the host. On the General tab, empty Password and untick Save password to OS keychain, which also removes a password saved earlier. Set Stored in an external secret manager instead? to None — use the password above, which drops any key file the host had.

2. On the Authentication tab, choose the identity under Use an Identity. The How do you sign in? section hides, and a line underneath says what the identity supplies.

3. Click Save changes.

When you connect, MangoSSH may still show the connect dialog asking for a password, because the host itself has none. Leave it empty and click Connect: the identity's credential is used. Anything you type there counts as the host's own and wins for that connect.

Rotate or delete

To rotate, change the identity's key file or password in Settings → Identities. Every host that uses it presents the new one next time; no host needs editing.

Deleting an identity also removes its secrets from the keychain. Hosts that used it fall back to their own settings. They keep the reference, shown as Missing identity, until you pick something else.

Limits

• SSH only. RDP and VNC hosts do not use identities yet. Use a group credential for RDP.
• No secret-manager methods. pass, Bitwarden, AWS SSM, Doppler and 1Password fetch per host at connect time, so there is nothing for an identity to hold. Set those on the host.
• Hardware methods carry no settings. An identity can say “PKCS#11” or “Windows Hello”, but the PKCS#11 module, key and PIN are per-host settings, and Windows Hello uses the computer's one hardware key. See Keys and sign-in methods.
• Secrets are per computer. The password and passphrase live in this computer's keychain. Set them again on each computer you use.

Groups

Every host has a Group on its General tab. Manage groups in Settings → Groups, or with the Manage groups button next to the Group field. The Settings page has SSH, RDP and VNC tabs. Groups belong to one protocol: an SSH group and an RDP group called “Production” are separate, with separate settings.

Each group row shows how many hosts it holds. SSH groups also have buttons to connect to, or disconnect from, every host in the group at once. The Default group cannot be deleted.

SSH group credential

1. Click Credential on the group's row.

2. Choose Password or Key only. For a password, type it, or leave it blank to be asked on connect. For a key, fill in Private key file path and, if the key is encrypted, Passphrase (if encrypted). Certificate path (optional) adds an OpenSSH certificate.

3. Click Save credential. The button changes to Credential ✓. A stored secret shows as “Stored — leave blank to keep” when you reopen it.

Clear removes the credential and its stored secrets, and leaves the group's default bastion alone. Group passwords and passphrases are kept in this computer's OS keychain.

RDP group credential

For RDP groups, Credential holds a Domain, Username and Password. They are used as one unit: a host with any of its own username, domain or password keeps its own login entirely and takes nothing from the group. When you pick the group for a new RDP host with those fields empty, the form fills them in so you can see what it will use.

VNC groups organise hosts only; they carry no credential or jump host.

Default jump host

SSH groups have a Default bastion list. Pick a saved SSH host, and every host in the group connects through it. On a host's Proxy tab, a line under Via SSH host shows when the jump host is inherited. Choose a bastion there to override it for that host. See Port forwarding and jump hosts for how the chain works.

Example: one deploy key, one exception

Twenty web servers accept the same deploy key, and one legacy box still needs a password.

1. Put the twenty hosts in an SSH group web, and give the group a Key only credential pointing at the deploy key. Set the group's Default bastion to your jump box.

2. On the legacy box, which is also in web, enter its password on the General tab and tick Save password to OS keychain. Because it has its own password, it ignores the group key, but still goes through the group's jump host.

3. When the deploy key is rotated, change the key path once, in the group credential.

Troubleshooting