Vault Quickstart: Difference between revisions
No edit summary |
No edit summary |
||
Line 59: | Line 59: | ||
* Click on '''Save''' | * Click on '''Save''' | ||
=== From Command Line === | ==== From Command Line ==== | ||
This example assumes you have already installed the vault binary and logged into the CS vault with your personal account. | This example assumes you have already installed the vault binary and logged into the CS vault with your personal account. | ||
* Create from json: | * Create from json: | ||
Line 75: | Line 75: | ||
<code>vault kv get personal/carnold/printers</code> | <code>vault kv get personal/carnold/printers</code> | ||
=== Through API === | ==== 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 <code>curl</code> | 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 <code>curl</code> | ||
* The previous command can be run as a direct API call, for example: | * The previous command can be run as a direct API call, for example: | ||
<code>curl s --header "X-Vault-Token: $(cat ~/.vault-token)" -X GET https://vault.enterprise.cs.vt.edu/v1/personal/carnold/printers | jq '.data'</code> | <code>curl s --header "X-Vault-Token: $(cat ~/.vault-token)" -X GET https://vault.enterprise.cs.vt.edu/v1/personal/carnold/printers | jq '.data'</code> | ||
* Read more about using the API on Hashicorp site: https://developer.hashicorp.com/vault/api-docs | * 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.enterprise.cs.vt.edu | |||
** Go to the shared CS transit key: https://vault.enterprise.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 | |||
** <code>vault:v1:zet0wHmvoEd/jmDlpgimDsvxBx09E8iJNUmMGBwLIco1/z7L0uLJGe7pkTgKW7Xm8qJpDtlO</code> | |||
** The data is not stored in the vault | |||
* Decrypt some data that you received | |||
** Log into https://vault.enterprise.cs.vt.edu | |||
** Go to the shared CS transit key: https://vault.enterprise.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: <code>echo SGVsbG8gZnJvbSB0aGUgcXVpY2tzdGFydCE= | base64 --decode</code> | |||
=== Why Use Vault? === | === Why Use Vault? === |
Revision as of 15:32, 6 February 2023
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.enterprise.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=cas
- It will give a URL that you need to open in a browser to finish the login
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
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.enterprise.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.enterprise.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.enterprise.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.enterprise.cs.vt.edu
- Go to the shared CS transit key: https://vault.enterprise.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.enterprise.cs.vt.edu
- Go to the shared CS transit key: https://vault.enterprise.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
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.