Mapping an SSH Key or Private Key Passphrase for Authentication

Some password changers may be customized to use SSH key authentication. Secret Server needs to know which text-entry fields contain the key and the passphrase. These text-entry fields can be specified after clicking Edit from the password changer page.

The key and passphrase must be identified by a $ sign and the secret text-entry field name, which can be obtained from the secret template.

Configuring Extended Mappings on the Secret Template

To tell Secret Server which text-entry fields hold the SSH private key and passphrase, configure the extended mappings on the secret template:

Search for Secret Templates. The Secrets Administration page is displayed.
In the Core Actions section, click Secret Templates. The list of available templates is displayed.
Select the template you want to configure, for example Unix Account (SSH Key Rotation), then click the Mapping tab.
If no SSH Private Key mapping exists, click Add Mapping to create one.

Selecting the Mapping Type

When adding a new extended mapping, the Mapping Type dropdown offers several options. For SSH key rotation, select SSH Private Key. This mapping type exposes three extended fields that must be mapped to the corresponding secret template fields. For more on the other available mapping types, see Creating or Editing Secret Templates.

Table: SSH Private Key Extended Fields

Extended Field	Maps to Secret Field	Purpose
PRIVATEKEY	Private Key	Identifies the field that stores the SSH private key.
PASSPHRASE	Private Key Passphrase	Identifies the field that stores the passphrase protecting the private key.
PUBLICKEY	Public Key	Identifies the field that stores the SSH public key.

Passphrase Behavior During Key Rotation

If the PASSPHRASE extended field is not mapped, Secret Server generates SSH keys without a passphrase during key rotation. The resulting private key is unencrypted.

If your security policy requires passphrase-protected keys, ensure the PASSPHRASE field is mapped to the template field that holds the passphrase value. When the mapping is present, Secret Server generates a passphrase and uses it to encrypt the new private key each time the key is rotated.

Generating a key without a passphrase is a supported configuration for application-to-application SSH, where no user is available to supply a passphrase. See Rotating SSH Keys Without a Passphrase for the use cases and security trade-offs.

When Mappings Are Needed

The built-in SSH Key templates ship with these extended mappings pre-configured. You typically only need to add or verify mappings in the following scenarios:

You created a custom template for Unix or Linux secrets and want to enable SSH key rotation on it.
You duplicated an existing template and the extended mappings were not carried over.
You renamed the key-related fields on a template and need to re-map them.

Extended Mappings and Launchers

Once Secret Server knows which text-entry fields contain the private key and private key passphrase, it can automatically use them as part of launchers, in addition to using them for key rotation.