»Vault SSH Secrets Engine: One-Time SSH Password
In a distributed cloud environment, tenant and system is increasingly important part of the online security. If an attacker gains access to your virtual machines, they can get control of most running applications, local data as well as its connected machines and systems.
The Vault SSH secrets engine provides secure authentication and authorization for access to machines via the SSH protocol. It supports signed SSH certificate and one-time SSH password modes. This guide demonstrates the one-time SSH password mode.
»Reference Material
»Estimated Time to Complete
10 minutes
»Personas
The end-to-end scenario described in this guide involves two personas:
-
operations
with privileged permissions to setup SSH secrets engine -
client
trusted entity to request SSH OTP from Vault
»Challenge
By default, SSH servers use password authentication with optional public key authentication. If any user on the system has a fairly weak password, this allows an attacker to hijack the SSH connection.
»Solution
Vault can create a one-time password (OTP) for SSH authentication on a network every time a client wants to SSH into a remote host using a helper command on the remote host to perform verification.
An authenticated client requests an OTP from the Vault server. If the client is authorized, Vault issues and returns an OTP. The client uses this OTP during the SSH authentication to connect to the desired target host.
When the client establishes an SSH connection, the OTP is received by the Vault helper which validates the OTP with the Vault server. The Vault server then deletes this OTP, ensuring that it is only used once.
Since the Vault server is contacted during SSH connection establishment, every login attempt and the correlating Vault lease information is logged to the audit secrets engine.
»Prerequisites
To perform the tasks described in this guide, you need to have a Vault environment. Refer to the Getting Started guide to install Vault.
»Policy requirements
NOTE: For the purpose of this guide, you can use root
token to work
with Vault. However, it is recommended that root tokens are only used for
initial setup or in emergencies. As a best practice, use tokens with
appropriate set of policies based on your role in the organization.
To perform all tasks demonstrated in this guide, your policy must include the following permissions:
If you are not familiar with policies, complete the policies guide.
»Steps
You will perform the following:
»Step 1: Install vault-ssh-helper
(Persona: operations)
The SSH secrets engine uses Vault SSH Helper to verify the OTP used during the SSH authentication. Therefore, the helper agent must be installed onto every target host.
-
Download and install the latest version of
vault-ssh-helper
from releases.hashicorp.com.Example:
-
Create a Vault SSH Helper configuration file,
/etc/vault-ssh-helper.d/config.hcl
.Where the
<VAULT_ADDRESS>
is the address of the Vault server generating the OTP.Example:
Refer to the documentation for the entire list of configuration properties.
-
Modify the
/etc/pam.d/sshd
file as follows:NOTE:
common-auth
is the standard Linux authentication module which is commented out in favor of using our custom configuration.Refer to the documentation for details about these parameter settings.
-
Modify the
/etc/ssh/sshd_config
file.This enables the keyboard-interactive authentication and PAM authentication modules. The password authentication is disabled.
-
Restart the SSH service:
This step must be performed on all target hosts that you wish to connect using the Vault's one-time SSH password.
»Step 2: Setup the SSH Secrets Engine
(Persona: operations)
On the Vault server, you must enable the SSH secrets engine before you can
perform the operation. Then you are going to create a role named,
otp_key_role
.
»CLI command
First, enable the SSH secrets engine.
Next, create a role.
This creates otp_key_role
with ubuntu
as its default username for which a
credential will be generated.
»API call using cURL
Enable ssh
secret engine using /sys/mounts
endpoint:
Where <TOKEN>
is your valid token, and <PARAMETERS>
holds configuration
parameters of the secret engine.
Example:
The following example enables SSH secret engine at sys/mounts/ssh
path, and passed the secret engine type (ssh
) in the request payload.
Now, create a role using the ssh/roles/otp_key_role
endpoint.
This creates otp_key_role
with ubuntu
as its default username for which a
credential will be generated.
»Web UI
Open a web browser and launch the Vault UI (e.g. http://127.0.0.1:8200/ui
) and
then login.
Select Enable new engine and select SSH from Secrets engine type drop-down list.
Click Enable Engine.
Select Create role.
Enter
otp_key_role
in the Role name field, select otp from the Key type drop-down list, and then enterubuntu
in the Default user field.-
Select More options to expand the optional parameter fields, and then enter
0.0.0.0/0
in the CIDR list field. Click Create role.
NOTE: Its recommended to create individual roles for each username to
ensure absolute isolation between usernames. This is required for Dynamic Key
type and OTP type. For the purpose of this guide, the cidr_list
will be
set to 0.0.0.0/0
. For production, be sure to set this parameter to be as
granular as you can since there is no need to keep this role open to the world.
»Step 3: Request an OTP
(Persona: client)
The client must have the following permission to request an OTP for
otp_key_role
.
»CLI command
To generate an OTP credential for an IP of the remote host belongs to the
otp_key_role
:
Example:
The key
value is the OTP to use during SSH authentication.
»API call using cURL
To generate an OTP credential for an IP of the remote host belongs to the
otp_key_role
:
Example:
The key
value is the OTP to use during SSH authentication.
»Web UI
To generate an OTP credential for an IP of the remote host belongs to the
otp_key_role
:
Select
ssh
under Secrets Engines.Select otp_key_role and enter
ubuntu
in the Username field, and enter the target host's IP address (e.g.192.0.2.10
) in the IP Address field.Click Generate.
Click Copy credentials. This copies the OTP (
key
value).
»Step 4: Establish an SSH session
Simply, use the OTP generated at Step 3 to authenticate:
NOTE: If sshpass
is installed,
you can create a new OTP and SSH into the target host with single line of CLI
command:
»Next steps
Read the Signed SSH Certificates documentation if you want to use signed SSH certificate so that the clients can use their local SSH keys to connect to the target hosts.