Add HashiCorp Vault key manager plugin to SPIRE server #5500
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -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., <https://vault.example.com:8443/>) | `${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" { | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 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" { | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| plugin_data { | ||||||
| vault_addr = "https://vault.example.org/" | ||||||
| pki_mount_point = "test-pki" | ||||||
| ca_cert_path = "/path/to/ca-cert.pem" | ||||||
| token_auth { | ||||||
| token = "<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" { | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 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 = "<Role ID>" // or specified by environment variables | ||||||
| approle_secret_id = "<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" { | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| 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" | ||||||
| // } | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should have a note here, that this is only for test environments.