Using the vault cli client

Installation

Download and install the vault binary for your OS by following the instructions on the Vault Downloads page.
Set the VAULT_ADDR environment variable to point to Sikt Vault.

export VAULT_ADDR=https://vault.sikt.no:8200

tip

Add VAULT_ADDR to your .profile or similar initalizing file for your shell.

Login

You use the Microsoft AzureAD configured authentication endpoint when logging in. Like this:

vault login -method=oidc mount=microsoft

Vault CLI will automatically launch your configured default browser, and open the very-long-microsoftonline.com-url shown.
After you complete the authentication, it will store your token in your home directory ($HOME), in a file called .vault-token. It will also print some metadata to the screen, like how long the token is valid and which policies are attached to it.

Vault CLI on a server through ssh

If you need to run vault on a server you log in to using ssh, you need to forward port tcp/8250 locally:

ssh -L 8250:localhost:8250 myserver.subdomain.sikt.no

Then perform the vault login, like above (vault login ...). The Vault CLI will not be able to open your browser automatically, so you must open the shown URL (login.microsoftonline.com-something) manually. Just copy-paste it or use a open-url functionality in your terminal window.
After logging in, you may see one or more error messages like this:

channel 3: open failed: connect failed: Connection refused

Which can be safely ignored.

If you need to use a jumphost (example: login.sikt.no), you can even add -J:

ssh -J login.sikt.no -L 8250:localhost:8250 myserver.subdomain.sikt.no

tip

Pro Tip: If you need to use the Vault CLI on a server like this many times, every now and then, or on many servers, add stanzas for them in your $HOME/.ssh/config file, adding host parameters like ProxyJump and DynamicForward. See the ssh_config man page for docs. Will save you a lot of hassle and typing.

Basic usage

Now that you have a token, you can interact with Vault according to the policies attached to your token.
Secrets are stored (or generated) using a secrets engine, and mounted in the root of a filesystem-like hierarchy (path-based).
The secrets engine we use for storing simple secrets (like passwords and API keys) is called "Key-Value store v2". It is mounted under /secret. The CLI command kv is used for interacting with this type of engine. Let's take a look at some of the operations you can perform on paths in the kv2 store:

LIST: listing content

To list the secrets at the toplevel:

$ vault kv list secret
Keys
----
project/

Here, we have a subpath named project. But no secrets. Let's take a look at what's in the subpath:

$ vault kv list secret/project
Keys
----
test

There is a secret named test inside the project subpath.

GET: reading secrets

Let's fetch the content of the secret:

$ vault kv get secret/project/test
====== Secret Path ======
secret/data/project/test

======= Metadata =======
Key                Value
---                -----
created_time       2023-08-29T12:53:23.495712103Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

====== Data ======
Key         Value
---         -----
username    test

The 'test' secret contained a single key-value pair: username = test.
We also get the metadata, which tells us that this is the first version of the secret. It also tells us when this version was created.

PUT: writing secrets

Let's create a new secret in the project path, named APIkeys:

$ vault kv put secret/project/APIkeys admintoken=eaxaeyeV3s
======= Secret Path =======
secret/data/project/APIkeys

======= Metadata =======
Key                Value
---                -----
created_time       2023-08-29T13:09:04.09865072Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Common use-cases

Reading the stored root password of a server

vault kv get secret/system/machines/myserver

or with less output:

vault kv get -field=value secret/system/machines/myserver

Updating the stored root password of a server

echo -n $password|vault kv put secret/system/machines/myserver value=-

Writing a certificate

You need to have the private key and the certificate + chain as to separate files. If you don't, you may write them on a RAM drive, such as /dev/shm/«your-username»/

Certificates in Vault have a path, the path starts with secret/ and typically ends with the common name of the certificate. What's in between may vary due to Vault policies and access control lists. The path for the certificate must be writeable by you and readable by the server. This access is determined by roles, ask your Vault administrator for more details.

vault kv put secret/«dill»/crt/«hostname» \
	certificate=@/dev/shm/«your-username»/certificate.pem \
	private_key=@/dev/shm/«your-username»/private-key.pem