Vault Plugin: SSH Auth Backend

This is a standalone backend plugin for use with Hashicorp Vault. This plugin allows for SSH public keys and SSH certificates to authenticate with Vault.

• Vault Plugin: SSH Auth Backend
  • Getting Started
  • Usage
  • Developing
    • Dev setup
  • Using the plugin
    • Global configuration
      • ssh_ca_public_keys
      • secure_nonce
    • Roles
      • SSH certificate
      • SSH public keys
    • Logging in
      • SSH certificate
      • SSH public key
      • Using templated policies
    • Creating signatures
    • Using ssh-agent

Getting Started

This is a Vault plugin and is meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read this guide on how to get started with Vault.

To learn specifically about how plugins work, see documentation on Vault plugins.

Usage

$ vault auth enable -path=ssh vault-plugin-auth-ssh
Success! Enabled vault-plugin-auth-ssh auth method at: ssh/

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine.

Next, clone this repository into vault-plugin-auth-ssh.

To compile a development version of this plugin, run make build. This will put the plugin binary in the ./vault/plugins folders.

Run make start to start a development version of vault with this plugin.

Enable the auth plugin backend using the SSH auth plugin:

$ vault auth enable -path=ssh vault-plugin-auth-ssh
Success! Enabled vault-plugin-auth-ssh auth method at: ssh/

Dev setup

Look into the devsetup.sh script, this will build the plugin, build certsig and setup a test environment with ssh-client signing, ssh certificate and public key test.

Using the plugin

Global configuration

You may optionally set any of the standard Vault token parameters which will be used as defaults if not overridden in a role.

ssh_ca_public_keys

If you want to use ssh certificates you'll need to configure the ssh CA's which the certificates will validate against.

sshca in this example is a file containing your SSH CA. You can specify multiple CA's.

$ vault write auth/ssh/config ssh_ca_public_keys=@sshca

$ vault read auth/ssh/config
Key                   Value
---                   -----
secure_nonce          true
ssh_ca_public_keys    [ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDrLFN/LCDOjPw327hWfHXMOk9+GmP+pOl2JEG7eSfkzwVhumDU12swjnPQ9H1tZVWzcfufTg+PgMd/hP19ADkRxQ2CTbz7YUPdD6LvJOCRK8TK+tKliaFL9/lWFtlitERyk91ZSqGbROjtCyGlnetxY1+tF5NqLFtQ1tsPrxjjdRQoUMHlF8yv/VUxMOCjAmuqxKrEl5mfZJcnYpnfEBgWoZNTKAXkp6KJWLAxyiHPVTt7azyMzivCTZc8eCKXIInRpOMR7TvHGxPG8tHn2XrI01ni9zXQ+xG1sqxecPBSWU8fekKxwg5bikrWw4/9kCNvxrwBpf1IzlIKhugig8MP3+Jlrjp5BFXFuaQatIk6zLMkzDpE/iZwDZv5qicXdLK/nbKHmGqFWupcvfHUe6rh16TOYFbpnRMOEvTYpR/PfLlnQKcbkQgbDR01N8DfLetxt635C+ANU4N1ebQqjKkwb8ZPr2ryF/Y8Z1PV0x5H25r8UZyoGAXIsP3zkP0Ev40Bx3umlU/jR8nF6QQmXdbs2McfZFO2g0VsXSzUOR0L5s5Sd/uoUCcpz9nmKlgRIqHIhVGF3+FjrIaj3tXT7ucyPAsVVk/l4yhMQSuNtFi0eqZRPcdMiKff5W9PfVyEkpXTcSFweGPdVehZxPnM7DfH7axpg73OLWxvwVzkah31WQ==]
token_bound_cidrs          []
token_explicit_max_ttl     0s
token_max_ttl              0s
token_no_default_policy    false
token_num_uses             0
token_period               0s
token_policies             []
token_ttl                  0s
token_type                 default

secure_nonce

By default the secure_nonce config option is enabled. This means vault will generate a nonce for you with a lifetime of 30 seconds.
You can get this nonce by doing vault read auth/ssh/nonce the resulting nonce must be used to create a signature over. (see Creating signatures)

If you disable secure_nonce you can use timebased nonces. (this is a possible security risk)

Roles

You can create / list / delete roles which are used to link your certificate or public keys to Vault policies.

You may optionally set any of the standard Vault token parameters to override default values.

SSH certificate

Create a role with the policy ssh-policy bound to a certificate with the principal ubuntu.
(prerequisite: a SSH CA needs to be configured in auth/ssh/config)

$ vault write auth/ssh/role/ubuntu token_policies="ssh-policy" principals="ubuntu"

$ vault read auth/ssh/role/ubuntu
Key                        Value
---                        -----
principals                 [ubuntu]
public_keys                <nil>
token_bound_cidrs          []
token_explicit_max_ttl     0s
token_max_ttl              0s
token_no_default_policy    false
token_num_uses             0
token_period               0s
token_policies             [ssh-policy]
token_ttl                  0s
token_type                 default

SSH public keys

Create a role with the policy ssh-policy bound to a specific publickey.

$ vault write auth/ssh/role/ubuntu token_policies="ssh-policy" public_keys=@sshkey.pub

$ vault read auth/ssh/role/ubuntu
Key                        Value
---                        -----
principals                 <nil>
public_keys                [ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGg0xzFrvEYbZGkF5vWlHUutACUTLH7WMUG09NOi6skL]
token_bound_cidrs          []
token_explicit_max_ttl     0s
token_max_ttl              0s
token_no_default_policy    false
token_num_uses             0
token_period               0s
token_policies             [ssh-policy]
token_ttl                  0s
token_type                 default

SSH public key self-registration

If your Vault has another authentication method that users can use, perhaps one that requires more user interaction such as OIDC authentication, it is possible to use that other authentication method to securely enable users to register their own public keys for SSH authentication.

First, configure default standard token parameters for SSH authentication as above, so users do not have to choose them, especially the token_policies parameter. Next, configure the other authentication method with a policy that enables writing public keys to the auth/ssh/role path but doesn't allow other parameters. For example use a templated policy like this:

path "auth/ssh/role/{{identity.entity.aliases.<mount accessor>.name}}" {
    capabilities = ["create", "update"]
    denied_parameters = {
        "public_keys"   = ["@*"]
    }
    allowed_parameters = {
        "public_keys"    = []
    }
}

Logging in

SSH certificate

nonce=$(vault read -field nonce auth/ssh/nonce)
vault write auth/ssh/login role=<role> cert=@<certfile> nonce=$nonce signature=<base64encoded ssh signature over $nonce>

For example

vault write auth/ssh/login role=ubuntu cert=@id_rsa-cert.pub signature=7ou2bupUMNmMqcorurOnbKnpbh9Kc7aBrF7nk6li0AhgnYAzhgfgGB3qJqI4qmf9TIc/x3JoNzo+Xq7KqXOXCA== nonce=AQAAAA7XdbPVKJn3uwA8

Key                  Value
---                  -----
token                s.TpHP2eRCZNhuOENZUMas6YmV
token_accessor       7FFAcAnxKOyM8BYWEN2KfYzR
token_duration       768h
token_renewable      true
token_policies       ["default" "ssh-policy"]
identity_policies    []
policies             ["default" "ssh-policy"]
token_meta_role      ubuntu

See Creating signatures about how to create those.

SSH public key

nonce=$(vault read -field nonce auth/ssh/nonce)
vault write auth/ssh/login role=<role> public_key=@<publickey> nonce=$nonce signature=<base64encoded ssh signature over $nonce>

For example

$ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub signature=fiEHdDHClYJIlRNWMC6c5QpM3ePi1xJh1KB90NI7CedZh0Siya5SG8ohy6zOk7e5l8Mdhx/FelykL43KH+OwBw== nonce=AQAAAA7XdbTAIytAhQA8

Key                  Value
---                  -----
token                s.8L1uONTtaLHzZEtNw2oKmurk
token_accessor       SQ6jWOYKblSBFqywTezcdqVk
token_duration       768h
token_renewable      true
token_policies       ["default" "ssh-policy"]
identity_policies    []
policies             ["default" "ssh-policy"]
token_meta_role      ubuntu

See Creating signatures about how to create those.

Using templated policies

This plugin makes aliases available for use in Vault templated policies. These can be used to limit what secrets a policy makes available while sharing one policy between multiple roles. The defined role is always available in policies as {{identity.entity.aliases.<mount accessor>.name}}. In addition, a login can add any metadata keys with values to further limit secrets paths via the metadata parameter available as {{identity.entity.aliases.<mount accessor>.metadata.<metadata key>}}. The metadata parameter is a mapping of keys to values which should be input as JSON, for example:

For example

echo '{ "metadata": { "key1" : "val1", "key2": "val2" } }' | \
  vault write auth/ssh/login role=<role> public_key=@<publickey> nonce=<nonce> signature=<signature> -

will create the metadata keys "key1" and key2" with values "val1" and "val2", respectively.

Creating signatures

For now you can use the createsig tool to generate your signature and nonce.

This tool will print out a signature based on a nonce to be used with vault-plugin-auth-ssh

Need createsig <nonce> <key-path> <password>
eg. createsig 5f780af8-75ff-f209-cd31-500879e18640 id_rsa mypassword

If you don't have a password just omit it
eg. createsig 5f780af8-75ff-f209-cd31-500879e18640 id_rsa

You must get the nonce from vault read auth/ssh/nonce

For example:

$ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub $(createsig $(vault read -field nonce auth/ssh/nonce) vaultid_rsa)

$ vault write auth/ssh/login role=ubuntu cert=@id_rsa-cert.pub $(createsig $(vault read -field nonce auth/ssh/nonce) id_rsa)

With a pass

$ vault write auth/ssh/login role=ubuntu public_key=@id_rsa.pub $(createsig $(vault read -field nonce auth/ssh/nonce) id_rsa yourpass)

Using ssh-agent

Signatures can also be created using ssh-agent. See the vssh README and pylogin README for examples of how to do that.