vault-ssh-plus

README

vault-ssh-plus (vssh)

An enhanced implementation of vault ssh, wrapping the OpenSSH ssh client to eliminate the management overhead of using of short-lived SSH client keys CA-signed by @hashicorp Vault.

Features

• Support for all ssh(1) capabilities, including non-filesystem private keys (e.g. gpg-agent, PKCS#11, etc.).
• Automatic and transparent just-in-time delivery of short-lived, signed, single-use ssh client keys.
• Principal of Least Privilege: by default signed keys only permit the specific options required.
• Significantly lower memory overhead than vault ssh.
• Automatic username mapping for roles with a single, fixed entry in allowed_users (e.g. root, jenkins, ansible).

Requirements

• A HashiCorp Vault instance configured for SSH Client Key Signing, access to an appropriate role, and an SSH server configured to trust the Vault CA.
• An active Vault token (either in the VAULT_TOKEN environment variable, or – if the standard vault binary is available within $PATH – within a Vault Token Helper). The VAULT_ADDR environment variable must also be set.
• The ssh binary available within $PATH.
• A standard SSH private key (stored anywhere supported by ssh(1)), and the associated unsigned public key (default: ~/.ssh/id_rsa.pub).

Usage

In addition to all the options accepted by ssh(1), vssh accepts the following options:

$ vssh --help
Usage:
  vssh [options] destination [command]

Application Options:
      --version                           Show version

Vault SSH key signing Options:
      --path=                             Vault SSH Path (default: ssh) [$VAULT_SSH_PATH]
      --role=                             Vault SSH Role (default: default) [$VAULT_SSH_ROLE]
      --ttl=                              Vault SSH Certificate TTL (default: 300) [$VAULT_SSH_TTL]
  -P, --public-key=                       OpenSSH Public RSA Key to sign (default: ~/.ssh/id_rsa.pub) [$VAULT_SSH_PUBLIC_KEY]

Certificate Extensions:
      --default-extensions                Disable automatic extension calculation and request signer-default extensions [$VAULT_SSH_DEFAULT_EXTENSIONS]
      --agent-forwarding                  Force permit-agent-forwarding extension [$VAULT_SSH_AGENT_FORWARDING]
      --port-forwarding                   Force permit-port-forwarding extension [$VAULT_SSH_PORT_FORWARDING]
      --no-pty                            Force disable permit-pty extension [$VAULT_SSH_NO_PTY]
      --user-rc                           Enable permit-user-rc extension [$VAULT_SSH_USER_RC]
      --x11-forwarding                    Force permit-X11-forwarding extension [$VAULT_SSH_X11_FORWARDING]

Help Options:
  -h, --help                              Show this help message

If you need to override the SSH Client Key Signing mountpoint or role, this is most easily achieved by setting the VAULT_SSH_PATH and VAULT_SSH_ROLE environment variables in your shell rc.

Similarly, if you prefer an ed25519 or ecdsa key, override with VAULT_SSH_PUBLIC_KEY.

Example

$ export VAULT_ADDR=https://vault.example.com:8200 VAULT_SSH_PATH=ssh-client-signer VAULT_SSH_PUBLIC_KEY=~/.ssh/id_ed25519.pub
$ vault login -method=oidc
...
$ vssh -N -L8080:localhost:80 host.example.com
...

Installation

Manual

Download and extract the latest release.

macOS

brew install isometry/tap/vault-ssh-plus

Ansible

If you've already installed my release-from-github role:

ansible -m import_role -a name=release-from-github -e release_repo=isometry/vault-ssh-plus -e release_hashicorp_style=yes localhost

Troubleshooting

Refer to the Vault Documentation