arnecls/vault-plugin-tailscale

A HashiCorp Vault plugin for managing Tailscale authentication keys

vault-plugin-tailscale

A HashiCorp Vault plugin for generating device authentication keys for Tailscale. Generated keys are single use.

Installation

1. Download the binary for your architecture from the releases page
2. Generate the SHA256 sum of the plugin binary

SHASUM=$(sha256sum vault-plugin-tailscale | cut -d ' ' -f1)

3. Add the plugin to your Vault plugin catalog (requires VAULT_TOKEN to be set)

vault plugin register -sha256="${SHASUM}" secret vault-plugin-tailscale

4. Mount the plugin

vault secrets enable -path=tailscale vault-plugin-tailscale 

Configuration

1. The ID of your tailnet is displayed on the top left of your admin console (your org name)
2. Obtain an API key or Oauth client credentials ("devices" scope) from the Tailscale admin dashboard.
3. Create the Vault configuration for the Tailscale API

# Authenticate through an API Key
vault write tailscale/config \
tailnet="${TAILNET}" \
api_key="${API_KEY}"

# Or use oauth client credentials
# Make sure to change the api_url!
vault write tailscale/config \
tailnet="${TAILNET}" \
oauth_client_id="${OAUTH_CLIENT_ID}" \
oauth_client_secret="${OAUTH_CLIENT_SECRET}" \
api_url='https://api.tailscale.com/api/v2/oauth/token'

Usage

Generate keys using the Vault CLI.

vault read tailscale/key

This will yield the following output:

Key          Value
---          -----
ephemeral    false
expires      2024-08-30T00:00:00Z
id           kMxzN47CNTRL
key          ....
reusable     false
tags         

Key Options

The following key/value pairs can be added to the end of the vault read command to configure key properties:

Tags

A comma separated list of tags to apply to the device that uses the authentication key. Keys must have a tag set. You can assign default tags to an oauth client on credential creation though.

vault read tailscale/key tags='tag:foo,tag:bar'

Preauthorized

If true, machines added to the tailnet with this key will not required authorization.

vault read tailscale/key preauthorized=true

Ephemeral

If true, nodes created with this key will be removed after a period of inactivity or when they disconnect from the Tailnet.

vault read tailscale/key ephemeral=true

Reusable

If true, the key can be reused for different nodes/devices. This is useful if you're dealing with ephemeral VMs or pods.

vault read tailscale/key reusable=true

lifetime

By default the lifetime of a generated key is 90d. You can set a shorter liftime if needed. Durations can be set using the standard golang duration notation.

vault read tailscale/key lifetime='24h'