Vault
HomeDocumentationTutorialsTry Cloud!
  • Vault
  • Documentation
    • What is Vault?
    • Use Cases
    • Setup
      • Install
      • Configuration
    • Get Started
      • Starting the server
      • Your first secret
      • Deploying Vault on VMs with Let's encrypt! TLS certs
    • Concepts
      • Operations
        • Seal/Unseal
        • "Dev" server mode
        • Namespace lock and unlock
        • Lease, renew, and revoke
        • Lease Explosions
        • Mount migration
        • Client count
        • Resource quotas
        • Response wrapping
      • Authentication
        • Identity
        • Tokens
        • OIDC provider
        • Username templating
        • Passwordless
      • Secrets
      • Storage
        • Integrated storage
        • High availability mode (HA)
        • Recovery mode
      • Policies
  • Tutorials
    • CLI
      • Operations
        • Deploy Vault
        • Using the HTTP API
        • Unseal/Seal
      • Authentication
        • Token
        • GitHub authentication
        • Username/Password
        • TLS Client Certificates
        • SSH Keys
        • AWS, Azure, GCP and external auth methods
          • Azure
          • AWS
          • GCP
          • Github
          • Terraform
      • Secrets
        • Secrets engines
        • Built-in help
      • Access Control
        • Policies
    • UI
      • Authentication
        • Username/Password
        • Passwordless
      • Operations
        • Unseal / Seal
        • API Explorer
      • Secrets
        • Secrets engines
      • Access Control
        • Policies
    • Use Cases
      • Namespaces
      • MongoDB admin password
      • VM Disk Encryption Keys
      • VM SSH Keys
      • Kubernetes Configuration
      • GitHub Actions
      • Dynamic credentials for cloud providers
        • AWS
        • Azure
        • GCP
  • CLI
    • agent
    • audit
    • auth
    • debug
    • delete
    • events
    • kv
    • lease
    • license
    • list
    • login
    • monitor
    • namespace
    • operator
    • patch
    • path-help
    • pki
    • plugin
    • policy
    • print
    • proxy
    • read
    • secrets
    • server
    • ssh
    • status
    • token
    • transit
    • unwrap
    • version
    • version-history
    • write
  • API
    • Secrets engines
      • AliCloud secrets engine (API)
      • AWS secrets engine (API)
      • Azure secrets engine (API)
      • Cubbyhole secrets engine (API)
      • Database
        • Cassandra database plugin HTTP API
        • Elasticsearch database plugin HTTP API
        • Influxdb database plugin HTTP API
        • MongoDB database plugin HTTP API
        • MSSQL database plugin HTTP API
        • MySQL/MariaDB database plugin HTTP API
        • Oracle database plugin HTTP API
        • PostgreSQL database plugin HTTP API
        • Redis database plugin HTTP API
        • Redis ElastiCache database plugin HTTP API
        • Redshift database plugin HTTP API
        • Snowflake database plugin HTTP API
      • Google Cloud secrets engine (API)
      • Google Cloud KMS secrets engine (API)
      • Identity
        • entity
        • entity-alias
        • group
        • group-alias
        • tokens
        • lookup
        • oidc-provider
        • MFA
          • duo
          • okta
          • pingid
          • totp
          • login-enforcement
      • KV secrets engine (API)
      • Buckypaper secrets engine
      • Kubernetes secrets engine (API)
      • Nomad secrets engine (API)
      • LDAP secrets engine (API)
      • PKI secrets engine (API)
      • RabbitMQ secrets engine (API)
      • SSH secrets engine (API)
      • TOTP secrets engine (API)
      • Transit secrets engine (API)
    • Auth engines
      • AliCloud auth method (API)
      • AppRole auth method (API)
      • AWS auth method (API)
      • Azure auth method (API)
      • Pivotal Cloud Foundry (CF) auth method (API)
      • GitHub auth method (API)
      • Google Cloud auth method (API)
      • JWT/OIDC auth method (API)
      • Kerberos auth method (API)
      • Kubernetes auth method (API)
      • LDAP auth method (API)
      • OCI auth method (API)
      • Okta auth method (API)
      • Passwordless auth method (API)
      • RADIUS auth method (API)
      • TLS certificate auth method (API)
      • Token auth method (API)
      • Userpass auth method (HTTP API)
    • Service engines
      • Licence Manager
    • System backend
      • /sys/audit
      • /sys/audit-hash
      • /sys/auth
      • /sys/capabilities
      • /sys/capabilities-accessor
      • /sys/capabilities-self
      • /sys/config/auditing/request-headers
      • /sys/config/control-group
      • /sys/config/cors
      • /sys/config/reload
      • /sys/config/state
      • /sys/config/ui
      • /sys/decode-token
      • /sys/experiments
      • /sys/generate-recovery-token
      • /sys/generate-root
      • /sys/health
      • /sys/host-info
      • /sys/in-flight-req
      • /sys/init
      • /sys/internal/counters
      • /sys/internal/inspect
        • /sys/internal/inspect/router
      • /sys/internal/specs/openapi
      • /sys/internal/ui/feature-flags
      • /sys/internal/ui/mounts
      • /sys/internal/ui/namespaces
      • /sys/internal/ui/resultant-acl
      • /sys/key-status
      • /sys/ha-status
      • /sys/leader
      • /sys/leases
      • /sys/license/status
      • /sys/locked-users
      • /sys/loggers
      • /sys/metrics
      • /sys/monitor
      • /sys/mounts
      • /sys/namespaces
      • /sys/plugins/reload/backend
      • /sys/plugins/catalog
      • /sys/plugins/runtimes/catalog
      • /sys/policy
      • /sys/policies/
      • /sys/policies/password/
      • /sys/pprof
      • /sys/quotas/config
      • /sys/quotas/rate-limit
      • /sys/quotas/lease-count
      • /sys/raw
      • /sys/rekey
      • /sys/rekey-recovery-key
      • /sys/remount
      • /sys/rotate
      • /sys/rotate/config
      • /sys/seal
      • /sys/seal-status
      • /sys/seal-backend-status
      • /sys/step-down
      • /sys/storage
        • /sys/storage/raft
        • /sys/storage/raft/autopilot
      • /sys/tools
      • /sys/unseal
      • /sys/version-history
      • /sys/wrapping/lookup
      • /sys/wrapping/rewrap
      • /sys/wrapping/unwrap
      • /sys/wrapping/wrap
  • Resources
    • Blog
    • GitHub
    • Youtube
    • CCx101
Powered by GitBook
On this page
  • Vault Plugin: SSH Auth Backend
  • Getting Started
  • Usage
  • Developing
  • Using the plugin
  1. Tutorials
  2. CLI
  3. Authentication

SSH Keys

PreviousTLS Client CertificatesNextAWS, Azure, GCP and external auth methods

Last updated 1 year ago

This is realized by

Vault Plugin: SSH Auth Backend

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

Getting Started

This is a 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.

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 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

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

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.

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

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

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

Using templated policies

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

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

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

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 )

You may optionally set any of the to override default values.

If your Vault has another authentication method that users can use, perhaps one that requires more user interaction such as , 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 like this:

See about how to create those.

See about how to create those.

This plugin makes aliases available for use in Vault . 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 now you can use the tool to generate your signature and nonce.

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

https://github.com/42wim/vault-plugin-auth-ssh
Vault
Vault plugin
Go
standard Vault token parameters
Creating signatures
standard Vault token parameters
OIDC authentication
templated policy
Creating signatures
Creating signatures
templated policies
createsig
vssh README
pylogin README