st2-auth-backend-vault 0.3.0

StackStorm authentication backend which reads credentials from an HashiCorp Vault instance.

HashiCorp Vault authentication backend for StackStorm

Overview

The HashiCorp Vault backend checks credentials and authenticates users against a HashiCorp Vault instance. Vault itself supports multiple different authentication methods detailed in their documentation. This backend can be configured to authenticate with any of the currently available Vault auth methods, however only one Vault Auth Method can be configured at a time.

Supported auth methods:

• app_id
• app_role
• aws
• azure
• gcp
• github
• kubernetes
• ldap
• okta
• radius
• token
• userpass

Configuration Options

option	required	default	description
vault_url	true		URL to the Vault API (ex: https://vault.domain.tld:8200)
auth_method	true		Name of the Vault auth method to use when authenticating
path	false	None	Alternate path/mount-point for the auth method. This is only needed if you did something like vault auth enable -path=mycustompath userpass, then you would set this variable equal to 'mycustompath'. Otherwise the default path for the auth method is used.
ssl_verify	false	True	Verify the SSL server certificates of the Vault server
ssl_ca_cert	false	None	Filesystem path to the SSL CA cert to use for SSL verification. Specifying this value automatically enables the ssl_verify parameter turning on SSL verification.
ssl_client_cert	false	None	Filesystem path to the SSL client certificate to use when communicating with the Vault API. If the client cert is split into a .cert and .key file then this is the path to the .cert file. Otherwise, if you have a bundled certificate and key in a .pem file, then this is the path to that .pem file.
ssl_client_key	false	None	Filesystem path to the SSL client certificate key to use when communicating with the Vault API. If the client cert is split into a .cert and .key file then this is the path to the .key file. Otherwise, do not specify this parameter

Configuration Example

Please refer to the authentication section in the StackStorm documentation for basic setup concept. The following is an example of the auth section in the StackStorm configuration file communicating with the Vault backend using the userpass auth method.

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "userpass"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: App ID

App ID is an auth method where you can authenticate using an application ID and a user ID. For more information on the App ID auth method, see the Vault App ID documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	App ID param
username	app_id
password	user_id

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <app_id>:<user_id> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <app_id>
Password: <user_id>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "app_id"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: App Role

App Role is an auth method where you can authenticate an application with a Vault-defined role using a generated secret. For more information on the App Role auth method, see the Vault App Role documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	App Role param
username	role_id
password	secret_id

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <role_id>:<secret_id> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <role_id>
Password: <secret_id>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "app_role"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: AWS

AWS is an auth method where you can authenticate using AWS IAM access key and secret keys . For more information on the AWS auth method, see the Vault AWS documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	AWS param
username	access_key
password	secret_key

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <access_key>:<secret_key> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <access_key>
Password: <secret_key>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "aws"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: Azure

Azure is an auth method where you can authenticate against Azure Active Directory. This works by creating a role in Vault that maps a name to a set of tenant information. The password is a signed JWT token from Azure Active Directory. For more information on the Azure auth method, see the Vault Azure documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	Azure param
username	role_name
password	jwt_token

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <role_name>:<jwt_token> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <role_name>
Password: <jwt_token>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "azure"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: GCP

GCP is an auth method where you can authenticate using Google credentials. This works by creating a role in Vault that maps a name to a set of tenant information. The password is a signed JWT token from the Google authentication entity. For more information on the GCP auth method, see the Vault GCP documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	GCP param
username	role_name
password	jwt_token

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <role_name>:<jwt_token> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <role_name>
Password: <jwt_token>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "gcp"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: GitHub

GitHub is an auth method where you can authenticate using a GitHub token. For more information on the GitHub auth method, see the Vault GitHub documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	GitHub param
username
password	token

NOTE In this auth method, the username is NOT used. The password is used for the GitHub token. Simply pass in any string as the username and then the GitHub token as the password.

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u unused:<token> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login unused
Password: <token>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "github"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: Kubernetes

Kubernetes is an auth method where you can authenticate against a Kubernetes cluster Service Account Token. This works by creating a role in Vault that maps a name to the service account information. The password is a signed JWT token for the Kubernetes service account. For more information on the Kubernetes auth method, see the Vault Kubernetes documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	Kubernetes param
username	role_name
password	jwt_token

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <role_name>:<jwt_token> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <role_name>
Password: <jwt_token>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "kubernetes"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: LDAP

LDAP is an auth method where you can authenticate against an existing LDAP server using username and password. LDAP binding information is configured within Vault when setting up the auth method. For more information on the LDAP auth method, see the Vault LDAP documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	LDAP param
username	username
password	password

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <username>:<password> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <username>
Password: <password>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "ldap"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: Okta

Okta is an auth method where you can authenticate against the Okta authentication service using a username and password. Okta account information is configured within Vault when setting up the auth method. For more information on the Okta auth method, see the Vault Okta documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	Okta param
username	username
password	password

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <username>:<password> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <username>
Password: <password>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "okta"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: RADIUS

RADIUS is an auth method where you can authenticate against an existing RADIUS server that accepts the PAP authentication scheme. RADIUS server information is configured within Vault when setting up the auth method. For more information on the Radius auth method, see the Vault Radius documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	RADIUS param
username	username
password	password

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <username>:<password> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <username>
Password: <password>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "radius"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: Token

Token is an auth method where you can authenticate using a Vault Token (built-in). For more information on the Token auth method, see the Vault Token documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	Token param
username
password	token

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u unused:<token> https://stackstorm.domain.tld/auth/v1/tokens

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login unused
Password: <token>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "token"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Auth Method: Userpass

Userpass is an auth method where you can authenticate using a Vault uername and password. For more information on the Userpass auth method, see the Vault Userpass documentation.

To utilize this method with StackStorm we will utilize the username and password parameters passed into the st2auth service and map them to the following parameters for this auth method:

st2auth param	Userpass param
username	username
password	password

Here's an example of authenticating, using this auth method, with a curl command:

curl -k -X POST -u <username>:<password> https://stackstorm.domain.tld/auth/v1/token

Here's an example of authenticating, using this auth method, with the st2 login command:

$ st2 login <username>
Password: <password>

The configuration for this auth method will look like the following:

[auth]
mode = standalone
backend = vault
backend_kwargs = {"vault_url": "https://vault.domain.tld:8200", "auth_method": "userpass"}
enable = True
logging = /path/to/st2auth.logging.conf
api_url = https://myhost.example.com:9101
debug = False

Development

To easily startup a Vault server simply run:

vagrant up

This boots up a Docker container running Vault.

You can run commands within this container like so:

vagrant docker-exec -- vault status

If you, for some reason, need to enter the container simply run:

vagrant docker-exec -it -- /bin/sh

To stop the container:

vagrant destroy

Development - Unit tests

Unit tests do not require the Vault container, instead the API is mocked out. To execute the unit tests we'll setup a virtualenv, install tox, then run tox.

virtualenv virtualenv
source ./virtualenv/bin/activate
pip install tox
tox -e py27,py36

You can also run the linting tests, after the virtualenv is activated:

tox -e lint

Or, you can run them both together:

tox -e py27,py36,lint

Development - Integration tests

Our integration tests rely on an instance of Vault running in a Docker container that is started and managed by Vagrant. To execute these tests you will need the following installed:

• Docker - install instructions here
• Vagrant - install instructions here

Once these dependencies have been installed we will tell Vagrant to start up our Vault container, and then execute our integration tests using tox (our virtualenv must be activated like above):

# start docker container with Vagrant
vagrant up

# setup virtualenv+tox
virtualenv virtualenv
source ./virtualenv/bin/activate
pip install tox

# run tests
tox -e integration

# stop docker container
vagrant destroy