vault-plugin-secrets-openstack

README

Vault Plugin: OpenStack Secrets Backend

This is a standalone backend plugin for use with Hashicorp Vault. This plugin generates revocable, time-limited Tokens and Users for OpenStack.

Quick Links

• OpenStack Secrets API Docs
• Vault Website
• Vault GitHub Project

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.

Setup

The setup guide assumes some familiarity with Vault and Vault's plugin ecosystem. You must have a Vault server already running, unsealed, and authenticated.

1. Download and decompress the latest plugin binary from the Releases tab on GitHub. Alternatively you can compile the plugin from source.

2. Move the compiled plugin into Vault's configured plugin_directory:

   $ mv vault-plugin-secrets-openstack /etc/vault/plugins/vault-plugin-secrets-openstack
   

3. Calculate the SHA256 of the plugin and register it in Vault's plugin catalog. If you are downloading the pre-compiled binary, it is highly recommended that you use the published checksums to verify integrity.

   $ export SHA256=$(shasum -a 256 "/etc/vault/plugins/vault-plugin-secrets-openstack" | cut -d' ' -f1)
   
   $ vault write sys/plugins/catalog/vault-plugin-secrets-openstack \
       sha_256="${SHA256}" \
       command="vault-plugin-secrets-openstack"
   
   Success! Data written to: sys/plugins/catalog/vault-plugin-secrets-openstack
   

4. Mount secrets engine:

   $ vault secrets enable \
       -path="openstack" \
       -plugin-name="vault-plugin-secrets-openstack" plugin
   
   Success! Enabled the vault-plugin-secrets-openstack secrets engine at: openstack/
   

Usage Guideline.

1. Firstly you have to define an admin credentials in a cloud.

   $ vault write /openstack/cloud/example-cloud auth_url=https://127.0.0.1/v3/ username=admin password=admin user_domain_name=mydomain
   Success! Data written to: openstack/cloud/example-cloud
   

   NOTE: In the cloud you can specify additional parameters such as username_template and password_policy in order to follow conventions and security policies defined in your OpenStack cloud.

2. After that you need to create a role for the cloud.

   $ vault write /openstack/role/example-role cloud=example-cloud project_name=myproject domain_name=mydomain user_roles="member" root=false
   Success! Data written to: openstack/role/example-role
   

3. Now you can easily create a temporary user/token pair.

   $ vault read /openstack/creds/example-role
   
   Key                Value
   ---                -----
   lease_id           openstack/creds/example-role/Kuma41Qu8s1k5f4AZ8PUmDxE
   lease_duration     1h
   lease_renewable    false
   auth_url           https://127.0.0.1/v3/
   expires_at         2022-04-19 02:03:36 +0000 UTC
   token              gAAAAABiXW-4r2Ofy4s4-oFlnbNgIrqONkmIHPnE...
   

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine (version 1.17+ is required).

For local dev first make sure Go is properly installed, including setting up a GOPATH. Next, clone this repository into $GOPATH/src/github.com/opentelekomcloud/vault-plugin-secrets-openstack.

To compile a development version of this plugin, run make and make install commands. This will put the plugin binary in the bin and $GOPATH/bin folders accordingly.

$ make
$ make install

Put the plugin binary into a location of your choice. This directory should be specified as the plugin_directory in the Vault config used to start the server.

...
plugin_directory = "path/to/plugin/directory"
...

Start a Vault server with this config file:

$ vault server -dev -dev-root-token-id=root -config=path/to/config.json

Once the server is started, register the plugin in the Vault server's plugin catalog:

$ vault write sys/plugins/catalog/vault-plugin-secrets-openstack \
        sha256=<expected SHA256 Hex value of the plugin binary> \
        command="vault-plugin-secrets-openstack"

Success! Data written to: sys/plugins/catalog/vault-plugin-secrets-openstack

Note you should generate a new sha256 checksum if you have made changes to the plugin. Example using openssl:

openssl dgst -sha256 $GOPATH/vault-plugin-secrets-openstack
...
SHA256(.../go/bin/vault-plugin-secrets-openstack)=896c13c0f2305daed381912a128322e02bc28a57d0c862a78cbc2ea66e8c6fa1

Enable the secrets' plugin backend using the secrets enable plugin command:

$ vault secrets enable -path=openstack -plugin-name=vault-plugin-secrets-openstack plugin
...
Successfully enabled the plugin-secrets-openstack secrets engine at: openstack/!

Tests

If you are developing this plugin and want to verify it is still functioning (and you haven't broken anything else), we recommend running the tests.

To run the tests, invoke make test:

$ make test

Acceptance Tests

Acceptance tests requires admin privileges in an OpenStack cloud.

$ export OS_CLIENT_CONFIG_FILE=<clouds.yaml path>
$ export OS_CLOUD=<cloud name>
$ make functional