Skip to content

Commit 307a2a7

Browse files
InverseIntegralInverseIntegral
committed
Add simple plugin documentation (#5058)
Signed-off-by: Matteo Kamm <[email protected]>
1 parent 4f1b244 commit 307a2a7

File tree

2 files changed

+163
-0
lines changed

2 files changed

+163
-0
lines changed

‎doc/plugin_server_keymanager_hashicorp_vault.md

+162
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Server plugin: KeyManager "hashicorp_vault"
2+
3+
The `hashicorp_vault` key manager plugin leverages HashiCorp Vault to create, maintain, and rotate key pairs, signing
4+
SVIDs as needed.
5+
6+
## Configuration
7+
8+
The plugin accepts the following configuration options:
9+
10+
| key | type | required | description | default |
11+
|:---------------------|:-------|:---------|:---------------------------------------------------------------------------------------------------------|:---------------------|
12+
| vault_addr | string | | The URL of the Vault server. (e.g., <https://vault.example.com:8443/>) | `${VAULT_ADDR}` |
13+
| namespace | string | | Name of the Vault namespace. This is only available in the Vault Enterprise. | `${VAULT_NAMESPACE}` |
14+
| transit_engine_path | string | | Path of the transit engine that stores the keys. | transit |
15+
| ca_cert_path | string | | Path to a CA certificate file used to verify the Vault server certificate. Only PEM format is supported. | `${VAULT_CACERT}` |
16+
| insecure_skip_verify | bool | | If true, vault client accepts any server certificates | false |
17+
| cert_auth | struct | | Configuration for the Client Certificate authentication method | |
18+
| token_auth | struct | | Configuration for the Token authentication method | |
19+
| approle_auth | struct | | Configuration for the AppRole authentication method | |
20+
| k8s_auth | struct | | Configuration for the Kubernetes authentication method | |
21+
22+
The plugin supports **Client Certificate**, **Token** and **AppRole** authentication methods.
23+
24+
- **Client Certificate** method authenticates to Vault using a TLS client certificate.
25+
- **Token** method authenticates to Vault using the token in a HTTP Request header.
26+
- **AppRole** method authenticates to Vault using a RoleID and SecretID that are issued from Vault.
27+
28+
The [`ca_ttl` SPIRE Server configurable](https://github.com/spiffe/spire/blob/main/doc/spire_server.md#server-configuration-file)
29+
should be less than or equal to the Vault's PKI secret engine TTL.
30+
To configure the TTL value, tune the engine.
31+
32+
e.g.
33+
34+
```shell
35+
$ vault secrets tune -max-lease-ttl=8760h pki
36+
```
37+
38+
The configured token needs to be attached to a policy that has at least the following capabilities:
39+
40+
```hcl
41+
path "pki/root/sign-intermediate" {
42+
capabilities = ["update"]
43+
}
44+
```
45+
46+
## Client Certificate Authentication
47+
48+
| key | type | required | description | default |
49+
|:----------------------|:-------|:---------|:---------------------------------------------------------------------------------------------------------------------|:-----------------------|
50+
| cert_auth_mount_point | string | | Name of the mount point where TLS certificate auth method is mounted | cert |
51+
| 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. | |
52+
| client_cert_path | string | | Path to a client certificate file. Only PEM format is supported. | `${VAULT_CLIENT_CERT}` |
53+
| client_key_path | string | | Path to a client private key file. Only PEM format is supported. | `${VAULT_CLIENT_KEY}` |
54+
55+
```hcl
56+
UpstreamAuthority "vault" {
57+
plugin_data {
58+
vault_addr = "https://vault.example.org/"
59+
pki_mount_point = "test-pki"
60+
ca_cert_path = "/path/to/ca-cert.pem"
61+
cert_auth {
62+
cert_auth_mount_point = "test-tls-cert-auth"
63+
client_cert_path = "/path/to/client-cert.pem"
64+
client_key_path = "/path/to/client-key.pem"
65+
}
66+
// If specify the role to authenticate with
67+
// cert_auth {
68+
// cert_auth_mount_point = "test-tls-cert-auth"
69+
// cert_auth_role_name = "test"
70+
// client_cert_path = "/path/to/client-cert.pem"
71+
// client_key_path = "/path/to/client-key.pem"
72+
// }
73+
74+
// If specify the key-pair as an environment variable and use the modified mount point
75+
// cert_auth {
76+
// cert_auth_mount_point = "test-tls-cert-auth"
77+
// }
78+
79+
// If specify the key-pair as an environment variable and use the default mount point, set the empty structure.
80+
// cert_auth {}
81+
}
82+
}
83+
```
84+
85+
## Token Authentication
86+
87+
| key | type | required | description | default |
88+
|:------|:-------|:---------|:------------------------------------------------|:-----------------|
89+
| token | string | | Token string to set into "X-Vault-Token" header | `${VAULT_TOKEN}` |
90+
91+
```hcl
92+
UpstreamAuthority "vault" {
93+
plugin_data {
94+
vault_addr = "https://vault.example.org/"
95+
pki_mount_point = "test-pki"
96+
ca_cert_path = "/path/to/ca-cert.pem"
97+
token_auth {
98+
token = "<token>"
99+
}
100+
// If specify the token as an environment variable, set the empty structure.
101+
// token_auth {}
102+
}
103+
}
104+
```
105+
106+
## AppRole Authentication
107+
108+
| key | type | required | description | default |
109+
|:-------------------------|:-------|:---------|:-----------------------------------------------------------------|:-----------------------------|
110+
| approle_auth_mount_point | string | | Name of the mount point where the AppRole auth method is mounted | approle |
111+
| approle_id | string | | An identifier of AppRole | `${VAULT_APPROLE_ID}` |
112+
| approle_secret_id | string | | A credential of AppRole | `${VAULT_APPROLE_SECRET_ID}` |
113+
114+
```hcl
115+
UpstreamAuthority "vault" {
116+
plugin_data {
117+
vault_addr = "https://vault.example.org/"
118+
pki_mount_point = "test-pki"
119+
ca_cert_path = "/path/to/ca-cert.pem"
120+
approle_auth {
121+
approle_auth_mount_point = "my-approle-auth"
122+
approle_id = "<Role ID>" // or specified by environment variables
123+
approle_secret_id = "<Secret ID>" // or specified by environment variables
124+
}
125+
// If specify the approle_id and approle_secret as an environment variable and use the modified mount point
126+
// approle_auth {
127+
// approle_auth_mount_point = "my-approle-auth"
128+
// }
129+
130+
// If specify the approle_id and approle_secret as an environment variable and use the default mount point, set the empty structure.
131+
// approle_auth {}
132+
}
133+
}
134+
```
135+
136+
## Kubernetes Authentication
137+
138+
| key | type | required | description | default |
139+
|:---------------------|:-------|:---------|:----------------------------------------------------------------------------------|:-----------|
140+
| k8s_auth_mount_point | string | | Name of the mount point where the Kubernetes auth method is mounted | kubernetes |
141+
| k8s_auth_role_name | string | ✔ | Name of the Vault role. The plugin authenticates against the named role | |
142+
| token_path | string | ✔ | Path to the Kubernetes Service Account Token to use authentication with the Vault | |
143+
144+
```hcl
145+
UpstreamAuthority "vault" {
146+
plugin_data {
147+
vault_addr = "https://vault.example.org/"
148+
pki_mount_point = "test-pki"
149+
ca_cert_path = "/path/to/ca-cert.pem"
150+
k8s_auth {
151+
k8s_auth_mount_point = "my-k8s-auth"
152+
k8s_auth_role_name = "my-role"
153+
token_path = "/path/to/sa-token"
154+
}
155+
156+
// If specify role name and use the default mount point and token_path
157+
// k8s_auth {
158+
// k8s_auth_role_name = "my-role"
159+
// }
160+
}
161+
}
162+
```

‎doc/spire_server.md

+1
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This document is a configuration reference for SPIRE Server. It includes informa
2020
|--------------------|--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
2121
| DataStore | [sql](/doc/plugin_server_datastore_sql.md) | An SQL database storage for SQLite, PostgreSQL and MySQL databases for the SPIRE datastore |
2222
| KeyManager | [aws_kms](/doc/plugin_server_keymanager_aws_kms.md) | A key manager which manages keys in AWS KMS |
23+
| KeyManager | [hashicorp_vault](/doc/plugin_server_keymanager_hashicorp_vault.md) | A key manager which manages unpersisted keys in memory |
2324
| KeyManager | [disk](/doc/plugin_server_keymanager_disk.md) | A key manager which manages keys persisted on disk |
2425
| KeyManager | [memory](/doc/plugin_server_keymanager_memory.md) | A key manager which manages unpersisted keys in memory |
2526
| CredentialComposer | [uniqueid](/doc/plugin_server_credentialcomposer_uniqueid.md) | Adds the x509UniqueIdentifier attribute to workload X509-SVIDs. |

0 commit comments

Comments
 (0)