Jutulind/smart_proxy_vault

Hashicorp Vault plugin for Smart Proxy

Smart Proxy - Hashicorp Vault Plugin

A Smart Proxy plugin that will return a Vault token after authenticating a client.

Design

The authentication portion of this plugin has been designed to be modular. Below is a current list of clients this plugin knows how to authenticate:

• Chef

If you're unable to use one of the above to authenticate your clients, you can always write your own & submit a PR (see DEVELOPMENT.md).

Installation

Add this line to your Smart Proxy's bundler.d/vault.rb gemfile:

gem 'smart_proxy_vault'

And then execute:

bundle install

Settings

Example:

---
:enabled: true
:auth_backend: 'chef'
:vault:
  :address: "https://vault.example.com"
  :token: "UUID"
  :ssl_verify: true
:add_token_metadata: true
:token_options:
  :policies: ['policyname']
  :ttl: '72h'
:chef:
  :endpoint: 'https://chef.example.com'
  :client: 'user'
  :key: '/path/to/client.pem'
  :ssl_verify: true

General

:enabled:

Toggles whether or not this plugin is enabled.

:auth_backend:

Specifies what authentication module you would like to use to authenticate your clients (must correspond to a filename in lib/smart_proxy_vault/authentication/)

:vault:

A hash of Vault settings that are used to configure a connection to the Vault server (determined by the Vault gem).

# https://github.com/hashicorp/vault-ruby/blob/master/lib/vault/configurable.rb
:vault:
  :address:
  :token:
  :open_timeout:
  :proxy_address:
  :proxy_password:
  :proxy_port:
  :proxy_username:
  :read_timeout:
  :ssl_ciphers:
  :ssl_pem_file:
  :ssl_pem_passphrase:
  :ssl_ca_cert:
  :ssl_ca_path:
  :ssl_verify:
  :ssl_timeout:
  :timeout:

:add_token_metadata:

If set to true, this plugin will add the requesting client's ID (as determined by the auth_backend) in the metadata & display-name fields when requesting a token.

:token_options:

A hash of parameters that will be passed to the token creation call except when requesting a role token (/auth/token/create).

Chef Backend

Only to be specified when the :auth_backend: is chef. Refer to the Chef backend documentation for more information.

:chef:

A hash of settings that are used to configure a connection to the Chef server (used by the Chef API gem).

# https://github.com/sethvargo/chef-api/blob/master/lib/chef-api/configurable.rb
:chef:
  :endpoint:
  :flavor:
  :client:
  :key:
  :proxy_address:
  :proxy_password:
  :proxy_port:
  :proxy_username:
  :ssl_pem_file:
  :ssl_verify:
  :user_agent:

Usage

To configure this plugin you can use template from settings.d/vault.yml.example. You must place the vault.yml config file in your Smart Proxy's config/settings.d/ directory.

The token specified in the :vault: section must be a role token so that this plugin can renew it indefinitely.

Endpoints

/vault/token/issue

Parameters

ttl=X[d,h,m,s]

Overrides the token TTL specified in the :token_options: section. However, this value must be lower than the Vault server's max_lease_ttl value.

Example:

/vault/token/issue?ttl=60s

role=foo

A role to assign the token. Tokens issued under roles are able to be renewed indefinitely. This is useful for applications like Consul Template. The role must be created on the Vault server first.

Example:

/vault/token/issue?role=foobar

Caveats

In order to use this plugin effectively, the Ruby installation on your Smart Proxy server should be version 2.0.0 or higher, and be compiled against a version of OpenSSL that supports TLS (=>1.0.1). I recommend using RVM & Passenger to run your Smart Proxy server.

$ irb
2.2.1 :001 > require 'openssl'
 => true
2.2.1 :002 > OpenSSL::OPENSSL_VERSION
 => "OpenSSL 1.0.1e 11 Feb 2013"