Service Account Key Operations

To create a new service account key:

1. In the Management Portal, browse to SSH > Service Account Keys.

2. On the Service Account Keys page, click Create.

   

   Figure 329: Add a Service Account Key

3. In the Key Information section of the Create dialog, select a Key Type in the dropdown (see Key Type).
4. In the Key Information section, select a Key Length in the dropdown (see Key Length). The available key lengths will vary depending upon the option select in the Key Type dropdown.
5. In the Key Information section, select a Server Group in the dropdown (see SSH Server Group Operations). The server group is used to control who has access in the Management Portal to the service account key. It does not limit where the key can be published. This field is required.
6. In the Key Information section, enter a Client Hostname reference for the service account key. This field is used for reference only and does not need to match an actual client hostname. It is used when building the full user name of the service account key for mapping to Linux logons for publishing to Linux servers (e.g. username@client_hostname). The naming convention is to enter the hostname of the server on which the application that will use the private key resides (e.g. appsrvr12), but you can put anything you like in this field (e.g. cheesetoast). This field is required.
7. In the User Information section of the page, enter the Username of the service account that will be using the key to connect to the target server (e.g. svc_myapp). This username will be combined with the Client Hostname to build the full user name of the service account key for mapping to Linux logons (e.g. svc_myapp@appsrvr12). You will need to know this full user name when creating the mappings to publish the public key to the target servers (see Edit Access to a Server Group, Edit Access to an SSH Server, or Add or Edit Access for an SSH Logon). This field is required.
8. In the User Information section of the page, enter the Email address of the administrator or group of administrators responsible for managing the key. This is the address to which key rotation alerts for this key will be directed (see Key Rotation Alerts). This field is required.

9. In the User Information section, enter a Passphrase to encrypt the downloaded copy of the private key of the key pair. The service that uses the private key will need to be able to provide it when connecting via SSH. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.

   Tip:  The private key downloads immediately at the conclusion of the creation process, encrypted with this passphrase. You may later download the private key again from this same page and encrypt it with a different passphrase, if desired.

10. In the Key Comment section, enter a Comment to include with the key. This field is optional.

    Tip:  Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may contain any characters supported for string fields, including spaces and most punctuation marks.

11. Click Save to save the new service account key.

    Tip:  Once the key pair is generated, an administrator needs to download the private key as an encrypted file and store it locally on the machine from which the service will make SSH connections using the private key. Additionally, an administrator needs to use Keyfactor Command to map the full user name built from the username and client hostname entered when generating the service account key pair (e.g. svc_myapp@appsrvr12) to the Linux logon account that the service account will operate as when logging in via SSH on the target server(s) where the public key needs to reside (see Edit Access to a Server Group, Edit Access to an SSH Server, or Add or Edit Access for an SSH Logon). After this is complete and the orchestrator Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores. has published the public key to the target server(s), the service may connect via SSH to the target server(s) using the new private key for authentication. For more information, see SSH.

Once you have generated an SSH key pair, most things about the key pair are fixed and cannot be changed. However, two pieces of key information can be changed for an existing key pair—the email address to which alerts about the key should be directed and the comment associated with the public key.

To modify the email address or key comment:

1. In the Management Portal, browse to SSH > Service Account Keys.
2. On the Service Account Keys page, double-click the key for the desired service account in the grid, highlight the row in the grid and click Edit at the top of the grid, or right-click the key in the grid and choose Edit from the right-click menu.

3. In the Edit Key dialog, update the Email and Comment fields as needed and click Save.

   

   Figure 330: Edit SSH Service Account Key Information

Changes made to the key comment will be published to any mapped logons on associated servers during the next synchronization cycle.

The rotate key option is used to replace an existing key that is approaching the end of its life or has been compromised. If key rotation alerts have been configured in the environment (see Key Rotation Alerts), the administrator responsible for managing the service account key will receive an email when the key is approaching the end if its lifetime to instruct the him or her to rotate the service account key.

The rotate dialog defaults to all the existing settings of the service account's current key. At its simplest, the administrator may choose to accept all the defaults, enter a passphrase to encrypt the downloaded private key and click save to generate the new key pair.

To rotate a service account key pair:

1. In the Management Portal, browse to SSH > Service Account Keys.

2. On the Service Account Keys page, click Rotate.

   

   Figure 331: Rotate an SSH Key Pair

3. In the Key Information section of the Rotate dialog, modify the existing Key Type in the dropdown, if desired (see Key Type).
4. In the Key Information section, modify the existing Key Length in the dropdown, if desired (see Key Length). The available key lengths will vary depending upon the option select in the Key Type dropdown.
5. In the User Information section, modify the existing Email address, if desired. This address is used for key rotation alerts (see Key Rotation Alerts). This field is required.
6. In the User Information section, enter a Passphrase to encrypt the downloaded copy of the private key of the key pair. You will need to provide this passphrase again when you use the private key to connect via SSH. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.

7. In the Key Comment section, modify the existing Comment to include with the key, if desired. This field is optional.

   Tip:  Although entry of an email address in the comment field of an SSH key is traditional, this is not a required format. The comment may can contain any characters supported for string fields, including spaces and most punctuation marks.
8. Click Save to create the new key pair.

To delete a service account key, highlight the row in the service account keys grid and click Delete at the top of the grid or right-click the key in the grid and choose Delete from the right-click menu.

After generating a key pair, you need to download the private key on the machine from which you will be making SSH connections. Although the private key is encrypted, for best security practice it should not be moved around from machine to machine.

The key downloads in the proprietary OpenSSH private key format, encrypted by a user-defined password.

Only the private key can be downloaded with the download option, though the public key is displayed in the edit dialog and may be copied and pasted to a file, if desired.

To download the private key:

1. In the Management Portal, browse to SSH > Service Account Keys.

2. On the Service Account Keys page, locate the key for the desired service account and click Download.

   

   Figure 332: Download a Service Account Private Key

3. In the Download dialog, enter a passphrase that will be used to encrypt the private key. By default, the minimum password length is 12 characters (see the SSH Key Password setting in Application Settings: SSH Tab). This field is required.

4. Click Download to save the file to the local machine.

   By default, the file has the following name:

   SSH-Key-Service-Account.identity