Create an SSH Rotated Secret

You can create a rotated secret for an SSH user. Before you get started, make sure you have created an SSH Target that includes the hostname and connection port, as well as credentials for an authorized user to change the users credentials.

Create an SSH Rotated Secret from the CLI

Let’s create an SSH rotated secret using the Akeyless CLI. If you’d prefer, see how to do this from the Akeyless Gateway UI instead.

The CLI command to create an SSH rotated secret is:

$ akeyless create-rotated-secret --name <secret name> \
--rotated-username <username> \
--rotated-password <password|private key>
--target-name <target name to associate> \
--rotator-creds-type[=use-self-creds]<use-self-creds|use-target-creds> \
--rotator_type <password|target>
--auto-rotate <true|false> \
--rotation-interval <1-365> \
--rotation_hour <hour in UTC>

where:

  • name: A unique name for the rotated secret. The name can include the path to the virtual folder in which you want to create the new secret, using slash / separators. If the folder does not exist, it will be created together with the secret.
  • rotated-username: The SSH user whose password should be rotated.
  • rotated-password: The SSH password to rotate.
  • target-name: The name of the SSh target with which the rotated secret should be associated.
  • rotator_type: The credential to be rotated, either password (default), to rotate the SSH user password specified in the rotated secret, or target, to rotate the password for the target credentials.
  • rotator-creds-type:Determines how to connect to the associated target: self-rotator-creds: Use the credentials defined for the rotated secret to connect.target-rotator-creds: Use the credentials defined for the associated target to connect.
  • auto-rotate: Optional, only required when the rotated secret should update the password. If this value is defined as true, specify the rotation-interval in days, and optionally also the rotation_hour.

👍

Tip

Select Target Rotator Creds if the rotated secret user is not authorized to change their own password, and a powerful user like the target user is required to change the password on behalf of the rotated secret user.

Options

The full list of options for this command is:

-n, --name                                 *Secret name
  -r, --target-name                          *The target name to associate
  -u, --gateway-url[=http://localhost:8000]   API Gateway URL (Configuration Management port)
  -m, --metadata                              Metadata about the secret
  -t, --tag                                   List of the tags attached to this secret. To specify multiple tags use argument multiple times: -t Tag1 -t Tag2
  -k, --key                                   The name of a key that used to encrypt the secret value (if empty, the account default protectionKey key will be used)
      --auto-rotate                           Whether to automatically rotate every --rotation-interval days, or disable existing automatic rotation
      --rotation-interval                     The number of days to wait between every automatic rotation (1-365),custom rotator interval will be set in minutes
      --rotation-hour                         The Hour of the rotation in UTC
      --rotator-type                         *The rotator type password/target/api-key/custom
      --rotator-creds-type[=use-self-creds]   The credentials to connect with use-self-creds/use-target-creds
      --rotator-custom-cmd                    Custom rotation command (relevant only for ssh target)
      --ssh-username                          ssh username - deprecated, replace by rotated-username
      --ssh-password                          ssh password to rotate - deprecated, replace by rotated-password
      --api-id                                API ID to rotate (relevant only for rotator-type=api-key)
      --api-key                               API key to rotate (relevant only for rotator-type=api-key)
      --rotated-username                      username to be rotated, if selected "use-self-creds" at rotator-creds-type, this username will try to rotate its own password, if "use-target-creds" is selected, target credentials will be use to rotate the rotated-password (relevant only for rotator-type=password)
      --rotated-password                      rotated-username password (relevant only for rotator-type=password)
      --custom-payload                        Secret payload to be sent with rotation request (relevant only for rotator-type=custom)
      --profile                               Use a specific profile from your $HOME/.akeyless/profiles/ folder
      --username                              Optional username for various authentication flows
      --password                              Optional password for various authentication flows
      --uid-token                             The universal identity token, Required only for universal_identity authentication
  -h, --help                                  display help information
      --json[=false]                          Set output format to JSON
      --no-creds-cleanup[=false]              Do not clean local temporary expired creds

Create an SSH Rotated Secret from the Akeyless Gateway UI

Let’s create a rotated secret using the Akeyless Gateway UI. If you’d prefer, see how to do this from the Akeyless CLI instead.

  1. Log in to the Akeyless Gateway, and select Rotated Secret > New > Create new rotated secret.

  2. Give the rotated secret a name, and define where it should be saved.

  3. Define the rest of the rotated secret settings as follows:

Field

Description

Authenticate with the following credentials

Determines how to connect to the associated target:
User Credentials: Use the credentials defined for the rotated secret to connect.
Target Credentials: Use the credentials defined for the associated target to connect.

Select Target Credentials if the rotated secret user is not authorized to change their own password, and a powerful user like the target user is required to change the password on behalf of the rotated secret user.

Rotation interval (in days)

Defines the number of days (1-365) to wait between automatic password rotations when Auto Rotate is enabled.

Rotation hour (local time zone)

Defines the time the password is rotated when Auto Rotate is enabled.

Auto rotate

Determines if automatic rotation is enabled.

Target

Defines the name of the target to be associated with the secret.

Username

Defines the SSH username whose password should be rotated.

Password

Defines the SSH password to rotate.

Rotator type

Determines the rotator type:
Password rotation: Rotate the password defined for the rotated secret.
Target rotation: Rotate the password defined for the associated target.

Rotation Statement

Optional - to create a custom rotation statement

Encrypt with the following Key

To enable zero-Knowledge, select a key with a Customer Fragment. For more information about zero-knowledge, see Implement Zero Knowledge.

👍

You can rotate the username and password for the target too, by creating a rotated secret with the rotator-type set as target. When you using a target rotator, the access role with which it is associated must have read and update permissions.

Custom Rotation Statement

Akeyless Rotated Secret for an SSH target supports a Custom Rotation Statement which enables flexibility in the form of triggering a destination application to rotate the password.

The Custom Rotation Statement provides 3 different arguments: USERNAME, NEW_PASSWORD, OLD_PASSWORD those arguments, can be used within any script, which will run upon password rotation attempt on the target server.

where:

  • USERNAME: The configured username within the Target or Rotated password whose password should be rotated.
  • OLD_PASSWORD: The old password to rotate.
  • NEW_PASSWORD: The new password generated by Akeyless.

Upon successful execution of your script, the password rotation will be updated.

For example, you can run a custom rotation command on an SSH target, either on a Windows or a Linux host, that will trigger a local script execution, or any supported command by your OS, to update the password for an existing application on your target host.

exec_command {{USERNAME}} {{NEW_PASSWORD}} {{OLD_PASSWORD}}

Where exec_command should be replaced with your script name, or by any existing command your target OS support.


Did this page help you?