Vault Quickstart

CS Vault Quickstart Guide

This guide will give you an introduction to using the Computer Science vault. We will show you how to do things both in the web interface and through command line access.

Introduction

The CS vault is a secrets store based on Hashicorp Vault https://www.vaultproject.io/ It allows you to securely store secrets such as passwords, certificates, and private keys. The data is stored encrypted and transmitted encrypted. It is all API driven, so can be integrated easily into your applications.

Authentication

All access to the CS vault is made through temporary tokens. Generally you do not personally use a token to log into the service unless you are directly access the API. Either the vault agent command line or the web interface will manage the temporary tokens for you once you log in with another method.

• We offer multiple authentication methods
• Each method logs in you into a separate identity that will have separate access levels even if the username is the same. For example, "carnold" logged in through CAS is not the same as "carnold" logged into through LDAP.

CAS

Using CAS login is the easiest way to log into the CS vault website https://vault.cs.vt.edu

• Select cas tab from the login screen
• Click on "Sign in with OIDC Provider" and another window will open with CS CAS Login if needed.
• CAS login can be used with command line interface as well
  • vault login -method=oidc -path=cas
  • It will give a URL that you need to open in a browser to finish the login
  • You must run the browser on the same machine that you are running vault command line

LDAP

You can use traditional CS username/password to log into CS Vault through the web interface or the command line interface.

• LDAP is best suited for command line interface
• Vault policies can be applied to your LDAP login based on your LDAP group memberships -- for example a shared group secrets path
• Login from vault command line
  • vault login -method=ldap username=<username>
  • It will prompt you for your password

AppRole

We also provide Vault's AppRole authentication. Find out more about AppRole: https://developer.hashicorp.com/vault/docs/auth/approle

• This method is meant as a systematic way for applications to access the vault API
• Techstaff will have to create a unique AppRole login for each of your applications and apply policies based on your specific needs.
• We recommend you use vault agent to manage your App's access to vault, this will greatly reduce the complexity of your application. See: https://developer.hashicorp.com/vault/docs/agent

Web Interface

Using the CS Vault web interface is the quickest and easiest way to get started using CS Vault.

• https://vault.cs.vt.edu
• You can log into the web interface using any of the supported authentication methods

Command Line Interface

Vault offers a command line interface. You will need to download a binary for your system to run it.

• Download: https://developer.hashicorp.com/vault/downloads
• You will need to tell the vault command line which vault server to connect to either through a command line option or environment variable
• Example:

export VAULT_ADDR=https://vault.cs.vt.edu
vault login -method-ldap username=carnold
vault list personal/carnold

• By default the command line will store the token at ~./vault-token
• You can effectively logout by removing the stored token: rm ~/.vault-token
• More information about the vault command line: https://developer.hashicorp.com/vault/docs/commands

Example: Personal Vault

The CS vault by default will give your CAS and LDAP logins access to a personal secrets path at /personal/<username> You can store any Key/Value items in this personal vault.

From Web Interface

• Click on the Secrets tab at the top
• Click on personal from the secrets list
• Click on Create secret to create a new secret
• Fill in Path for this secret with <username>/<my-secret-name> Example: carnold/printers
• Fill in Secret data with any number of key = value pairs you want. The key is displayed in clear text and the value is kept secret.
• 
• Click on Save

From Command Line

This example assumes you have already installed the vault binary and logged into the CS vault with your personal account.

• Create from json:

vault kv put personal/carnold/printers - <<EOF
{
  "username": "myuser",
  "password": "supersecret"
}
EOF

• List keys for a path:

vault kv list personal/carnold

• Display all values in a secret:

vault kv get personal/carnold/printers

Through API

Using the vault command is really just a wrapper for the accessing the vault API. You can access the API directly using a tool such as curl

• The previous command can be run as a direct API call, for example:

curl s --header "X-Vault-Token: $(cat ~/.vault-token)" -X GET https://vault.cs.vt.edu/v1/personal/carnold/printers | jq '.data'

• Read more about using the API on Hashicorp site: https://developer.hashicorp.com/vault/api-docs

Encryption as a Service

The CS Vault has the ability to use named keys that CS vault manages to encrypt or decrypt data on the fly for you. Vault calls this transit secrets. This allows you securely encrypt data without actually storing the secret in the CS Vault. For example, you might want to email another CS colleague a password but not in plain text. CS vault can take your plain text password and encrypt it such that only someone with access the same named key in CS vault can decrypt. By default all CS Vault users get access to a shared key named cs. This is an example of using the shared key.

Through Web UI

• Encrypt some data
  • Log into https://vault.cs.vt.edu
  • Go to the shared CS transit key: https://vault.cs.vt.edu/ui/vault/secrets/transit/show/cs?tab=actions
  • Click on Encrypt
  • Enter the secret data you want to transmit
  • Click on Encrypt button
  • It will output your encrypted data that you can now share in plain text
  • vault:v1:zet0wHmvoEd/jmDlpgimDsvxBx09E8iJNUmMGBwLIco1/z7L0uLJGe7pkTgKW7Xm8qJpDtlO
  • The data is not stored in the vault
• Decrypt some data that you received
  • Log into https://vault.cs.vt.edu
  • Go to the shared CS transit key: https://vault.cs.vt.edu/ui/vault/secrets/transit/show/cs?tab=actions
  • Click on Decrypt
  • Enter the encrypted data you want to decrypt
  • Click on Decrypt' button
  • It will output the decrypted data as a base64 string
  • You can view the plain text by converting the base64 string: echo SGVsbG8gZnJvbSB0aGUgcXVpY2tzdGFydCE= | base64 --decode

Through Command Line

This example assumes you have the vault binary installed and are logged into the CS Vault through the command line.

• Encrypt some data
  • vault write transit/encrypt/cs plaintext=$(base64 <<< "hello world")
• Decrypt some data
  • vault write transit/decrypt/cs ciphertext="vault:v1:jqRZ+MNF4dVx0CpIH8clMGXo98xGBwrzaaumBvhypjtmaapOXRlHCQ=="
  • Outputs as base64 string
  • Convert base64 string: echo aGVsbG8gd29ybGQ= || base64 --decode

Why Use Vault?

Some of the advantages of using a service like CS vault to store your secrets:

• Easier to use stronger more complex passwords that do not have to be stored in plain text
• Ability to securely share secrets with a group of users
• Store all your secrets in one location
• If you secrets are stored in one location and accessed dynamically, then you can quickly and easily rotate the secrets for improved security
• Once properly set up, you can revoke access to secrets from Apps or clients that may be compromised
• Vault provides an audit trail of exactly who has accessed which secrets

Custom Use Cases

The CS Vault can do lots more than just Key/Value storage. See Vault's website for more use case ideas: https://developer.hashicorp.com/vault/docs More advanced uses will generally require some level of collaboration with CS Techstaff to configure and use.