diff --git a/doc/plugin_server_keymanager_hashicorp_vault.md b/doc/plugin_server_keymanager_hashicorp_vault.md new file mode 100644 index 0000000000..fb3343e5c4 --- /dev/null +++ b/doc/plugin_server_keymanager_hashicorp_vault.md @@ -0,0 +1,162 @@ +# Server plugin: KeyManager "hashicorp_vault" + +The `hashicorp_vault` key manager plugin leverages HashiCorp Vault to create, maintain, and rotate key pairs, signing +SVIDs as needed. + +## Configuration + +The plugin accepts the following configuration options: + +| key | type | required | description | default | +|:---------------------|:-------|:---------|:---------------------------------------------------------------------------------------------------------|:---------------------| +| vault_addr | string | | The URL of the Vault server. (e.g., ) | `${VAULT_ADDR}` | +| namespace | string | | Name of the Vault namespace. This is only available in the Vault Enterprise. | `${VAULT_NAMESPACE}` | +| transit_engine_path | string | | Path of the transit engine that stores the keys. | transit | +| ca_cert_path | string | | Path to a CA certificate file used to verify the Vault server certificate. Only PEM format is supported. | `${VAULT_CACERT}` | +| insecure_skip_verify | bool | | If true, vault client accepts any server certificates | false | +| cert_auth | struct | | Configuration for the Client Certificate authentication method | | +| token_auth | struct | | Configuration for the Token authentication method | | +| approle_auth | struct | | Configuration for the AppRole authentication method | | +| k8s_auth | struct | | Configuration for the Kubernetes authentication method | | + +The plugin supports **Client Certificate**, **Token** and **AppRole** authentication methods. + +- **Client Certificate** method authenticates to Vault using a TLS client certificate. +- **Token** method authenticates to Vault using the token in a HTTP Request header. +- **AppRole** method authenticates to Vault using a RoleID and SecretID that are issued from Vault. + +The [`ca_ttl` SPIRE Server configurable](https://github.com/spiffe/spire/blob/main/doc/spire_server.md#server-configuration-file) +should be less than or equal to the Vault's PKI secret engine TTL. +To configure the TTL value, tune the engine. + +e.g. + +```shell +$ vault secrets tune -max-lease-ttl=8760h pki +``` + +The configured token needs to be attached to a policy that has at least the following capabilities: + +```hcl +path "pki/root/sign-intermediate" { + capabilities = ["update"] +} +``` + +## Client Certificate Authentication + +| key | type | required | description | default | +|:----------------------|:-------|:---------|:---------------------------------------------------------------------------------------------------------------------|:-----------------------| +| cert_auth_mount_point | string | | Name of the mount point where TLS certificate auth method is mounted | cert | +| cert_auth_role_name | string | | Name of the Vault role. If given, the plugin authenticates against only the named role. Default to trying all roles. | | +| client_cert_path | string | | Path to a client certificate file. Only PEM format is supported. | `${VAULT_CLIENT_CERT}` | +| client_key_path | string | | Path to a client private key file. Only PEM format is supported. | `${VAULT_CLIENT_KEY}` | + +```hcl + UpstreamAuthority "vault" { + plugin_data { + vault_addr = "https://vault.example.org/" + pki_mount_point = "test-pki" + ca_cert_path = "/path/to/ca-cert.pem" + cert_auth { + cert_auth_mount_point = "test-tls-cert-auth" + client_cert_path = "/path/to/client-cert.pem" + client_key_path = "/path/to/client-key.pem" + } + // If specify the role to authenticate with + // cert_auth { + // cert_auth_mount_point = "test-tls-cert-auth" + // cert_auth_role_name = "test" + // client_cert_path = "/path/to/client-cert.pem" + // client_key_path = "/path/to/client-key.pem" + // } + + // If specify the key-pair as an environment variable and use the modified mount point + // cert_auth { + // cert_auth_mount_point = "test-tls-cert-auth" + // } + + // If specify the key-pair as an environment variable and use the default mount point, set the empty structure. + // cert_auth {} + } + } +``` + +## Token Authentication + +| key | type | required | description | default | +|:------|:-------|:---------|:------------------------------------------------|:-----------------| +| token | string | | Token string to set into "X-Vault-Token" header | `${VAULT_TOKEN}` | + +```hcl + UpstreamAuthority "vault" { + plugin_data { + vault_addr = "https://vault.example.org/" + pki_mount_point = "test-pki" + ca_cert_path = "/path/to/ca-cert.pem" + token_auth { + token = "" + } + // If specify the token as an environment variable, set the empty structure. + // token_auth {} + } + } +``` + +## AppRole Authentication + +| key | type | required | description | default | +|:-------------------------|:-------|:---------|:-----------------------------------------------------------------|:-----------------------------| +| approle_auth_mount_point | string | | Name of the mount point where the AppRole auth method is mounted | approle | +| approle_id | string | | An identifier of AppRole | `${VAULT_APPROLE_ID}` | +| approle_secret_id | string | | A credential of AppRole | `${VAULT_APPROLE_SECRET_ID}` | + +```hcl + UpstreamAuthority "vault" { + plugin_data { + vault_addr = "https://vault.example.org/" + pki_mount_point = "test-pki" + ca_cert_path = "/path/to/ca-cert.pem" + approle_auth { + approle_auth_mount_point = "my-approle-auth" + approle_id = "" // or specified by environment variables + approle_secret_id = "" // or specified by environment variables + } + // If specify the approle_id and approle_secret as an environment variable and use the modified mount point + // approle_auth { + // approle_auth_mount_point = "my-approle-auth" + // } + + // If specify the approle_id and approle_secret as an environment variable and use the default mount point, set the empty structure. + // approle_auth {} + } + } +``` + +## Kubernetes Authentication + +| key | type | required | description | default | +|:---------------------|:-------|:---------|:----------------------------------------------------------------------------------|:-----------| +| k8s_auth_mount_point | string | | Name of the mount point where the Kubernetes auth method is mounted | kubernetes | +| k8s_auth_role_name | string | ✔ | Name of the Vault role. The plugin authenticates against the named role | | +| token_path | string | ✔ | Path to the Kubernetes Service Account Token to use authentication with the Vault | | + +```hcl + UpstreamAuthority "vault" { + plugin_data { + vault_addr = "https://vault.example.org/" + pki_mount_point = "test-pki" + ca_cert_path = "/path/to/ca-cert.pem" + k8s_auth { + k8s_auth_mount_point = "my-k8s-auth" + k8s_auth_role_name = "my-role" + token_path = "/path/to/sa-token" + } + + // If specify role name and use the default mount point and token_path + // k8s_auth { + // k8s_auth_role_name = "my-role" + // } + } + } +``` diff --git a/doc/spire_server.md b/doc/spire_server.md index 1304225cc7..dbc9ce773e 100644 --- a/doc/spire_server.md +++ b/doc/spire_server.md @@ -20,6 +20,7 @@ This document is a configuration reference for SPIRE Server. It includes informa |--------------------|--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | DataStore | [sql](/doc/plugin_server_datastore_sql.md) | An SQL database storage for SQLite, PostgreSQL and MySQL databases for the SPIRE datastore | | KeyManager | [aws_kms](/doc/plugin_server_keymanager_aws_kms.md) | A key manager which manages keys in AWS KMS | +| KeyManager | [hashicorp_vault](/doc/plugin_server_keymanager_hashicorp_vault.md) | A key manager which manages unpersisted keys in memory | | KeyManager | [disk](/doc/plugin_server_keymanager_disk.md) | A key manager which manages keys persisted on disk | | KeyManager | [memory](/doc/plugin_server_keymanager_memory.md) | A key manager which manages unpersisted keys in memory | | CredentialComposer | [uniqueid](/doc/plugin_server_credentialcomposer_uniqueid.md) | Adds the x509UniqueIdentifier attribute to workload X509-SVIDs. |