Skip to content

Commit ac0ba55

Browse files
ncabatoffncabatoff
committed
Add spiffe secrets engine docs
1 parent 3fcb114 commit ac0ba55

File tree

2 files changed

+229
-0
lines changed

2 files changed

+229
-0
lines changed

‎content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
layout: api
3+
page_title: SPIFFE - Secrets engines - HTTP API
4+
description: This is the API documentation for the Vault SPIFFE secrets engine.
5+
---
6+
7+
# SPIFFE secrets engine (API)
8+
9+
Use the SPIFFE plugin to mint SPIFFE JWT-SVIDs. The example code below assumes
10+
you mounted the SPIFFE plugin at `/spiffe`. Since it is possible to enable
11+
secrets engines at any location, please update your API calls accordingly.
12+
13+
## Create configuration
14+
15+
Configure the SPIFFE trust domain for the plugin.
16+
17+
| Method | Path |
18+
|:-------|:----------------------|
19+
| `POST` | `/spiffe/config` |
20+
21+
### Request parameters
22+
23+
- `trust_domain` `(string: <required>)` - The SPIFFE trust domain used by the
24+
plugin. You can omit the `spiffe://` prefix.
25+
- `bundle_refresh_hint` `(int or time string: "1h")` - The value to put as the refresh hint in trust bundles we publish.
26+
May not exceed key_lifetime/10.
27+
- `key_lifetime` `(int or time string: "24h")` - How often to generate a new signing key. Uses duration format strings.
28+
- `jwt_issuer_url` `(string: optional)` - The base URL to use for JWT issuer claims (`iss`), including
29+
`https://` schema, host, and optional port. Must be reachable by whatever systems consume the JWTs.
30+
By default it will be the vault cluster's api_addr. The mount path and issuer endpoint will be appended to this value.
31+
- `jwt_signing_algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default),
32+
RS384, RS512, ES256, ES384, ES512.
33+
- `jwt_oidc_compatibility_mode` `(bool: false)` - When set true, attempts to generate JWT SVIDs will fail if the resulting
34+
SPIFFEID exceeds 255 chars, the limit for JWT sub claims in OIDC.
35+
36+
### Sample payload
37+
38+
```json
39+
{
40+
"trust_domain": "example.org",
41+
"bundle_refresh_hint": "30m",
42+
"key_lifetime": "12h"
43+
}
44+
```
45+
46+
## Read configuration
47+
48+
Fetch the SPIFFE configuration details.
49+
50+
| Method | Path |
51+
|:-------|:----------------------|
52+
| `GET` | `/spiffe/config` |
53+
54+
### Request parameters
55+
56+
None.
57+
58+
### Sample response
59+
60+
```json
61+
{
62+
"bundle_refresh_hint": "3600",
63+
"jwt_issuer_url": "",
64+
"jwt_oidc_compability_mode": false,
65+
"jwt_signing_algorithm": "RS256",
66+
"key_lifetime": "86400",
67+
"trust_domain": "example.org"
68+
}
69+
```
70+
71+
## Create role
72+
73+
Create or update a named role that specifies the content of JWTs.
74+
75+
| Method | Path |
76+
|:-------|:--------------------------|
77+
| `POST` | `/spiffe/role/:name` |
78+
79+
### Path parameters
80+
81+
- `name` `(string: <required>)` - The unique name of the SPIFFE role you want to
82+
update.
83+
84+
### Request parameters
85+
86+
- `template` `(string: <required>)` - The template string to use for generating tokens. This may be in
87+
stringified JSON or base64 format.
88+
- `ttl` `(int or time string: "5m")` - TTL of the tokens generated against the role. Uses duration format strings.
89+
TTLs of generated tokens will be capped by the lifespan of the current signing key.
90+
- `use_jti_claim` `(bool: false)` - If true, the jti claim will be included in JWTs, which may impact
91+
their reusability.
92+
93+
Roles define a template in much the same way as [identity tokens](../identity/identity-token). As with identity tokens, some claims cannot be
94+
overridden by the template and are populated by the secrets engine:
95+
96+
- `iss`: Issuer URL is populated based on the global config setting jwt_issuer_url
97+
- `aud`: Audience is populated by the JWT minting endpoint argument
98+
- `iat`: Time of issue
99+
- `exp`: Expiration time for the token (iat + ttl)
100+
- `jti`: UUID that helps for audit trails and preventing replay attacks (rfc7519), present only if the role setting
101+
`use_jti_claim` is true
102+
103+
In addition to these standard claims, the following claim will be included to assist in provenance:
104+
- `vault: {entity: {id: ENTITY_ID}}`
105+
Here the entity id is that of the Vault client.
106+
107+
Unlike with identity tokens, `sub` can (and must) be specified. This is either the SPIFFEID of the JWT SVID, or
108+
the path part of a SPIFFEID, in which case the secrets engine will prepend `spiffe://` and the configured trust domain.
109+
Role creation will fail if the parsed template doesn't have a sub claim. SVID minting will fail if the expanded template
110+
isn't a valid SPIFFEID, or doesn't have the configured trust domain.
111+
112+
### Sample payload
113+
114+
```json
115+
{
116+
"template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\""
117+
}
118+
```
119+
120+
## Read role
121+
122+
Read the named SPIFFE role.
123+
124+
| Method | Path |
125+
|:-------|:--------------------------|
126+
| `GET` | `/spiffe/role/:name` |
127+
128+
### Path parameters
129+
130+
- `name` `(string: <required>)` - The unique name of the SPIFFE role you want to
131+
read.
132+
133+
### Sample response
134+
135+
```json
136+
{
137+
"template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"",
138+
"ttl": "300",
139+
"use_jti_claim": false
140+
}
141+
```
142+
143+
## Delete role
144+
145+
Delete the named SPIFFE role.
146+
147+
| Method | Path |
148+
|:---------|:--------------------------|
149+
| `DELETE` | `/spiffe/role/:name` |
150+
151+
### Path parameters
152+
153+
- `name` `(string: <required>)` - The unique name of the SPIFFE role you want to delete.
154+
155+
## List roles
156+
157+
List the names of all SPIFFE roles.
158+
159+
| Method | Path |
160+
|:-------|:--------------------|
161+
| `LIST` | `/spiffe/role` |
162+
163+
### Request parameters
164+
165+
None.
166+
167+
### Sample response
168+
169+
```json
170+
{
171+
"keys": [
172+
"example-role"
173+
]
174+
}
175+
```
176+
177+
## Mint JWT token
178+
179+
Creates and returns a JWT token based on the role's template, using JWT Compact Serialization format.
180+
181+
| Method | Path |
182+
|:-------|:---------------------|
183+
| `POST` | `/spiffe/role/:name/mintjwt` |
184+
185+
### Request parameters
186+
187+
- `audience` `(string: "")` - The value to use for the `aud` claim in the JWT token.
188+
189+
190+

‎content/vault/v1.22.x/content/docs/secrets/spiffe.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
layout: docs
3+
page_title: SPIFFE secrets engine
4+
description: >-
5+
The SPIFFE secrets engine allows users to mint SPIFFE JWT-SVIDs
6+
---
7+
8+
# SPIFFE secrets engine
9+
10+
@include 'alerts/enterprise-only.mdx'
11+
12+
The `spiffe` secrets engine allows for minting SPIFFE JWT-SVIDS using a
13+
template that can interpolate identity information about the requesting entity.
14+
These JWTs are OIDC-compatible and so can also be used in the same way
15+
as JWT tokens minted using the identity engine.
16+
17+
## Configuration
18+
19+
Each SPIFFE backend instance has a single trust domain. Roles are used to
20+
define templates that determine the claims in the minted JWTs.
21+
22+
## Integrate with SPIRE
23+
24+
The SPIFFE secrets engine has an endpoint `trust_bundle/web` that serves
25+
the trust bundle. This can be used by other systems that implement SPIFFE
26+
federation, e.g. [SPIRE](https://spiffe.io/spire/) or another Vault cluster
27+
running the [SPIFFE auth method.](../../auth/spiffe), in order to fetch
28+
the public keys needed to validate JWTs minted by this secret engine.
29+
30+
## Integrate with OIDC
31+
32+
The SPIFFE secrets engine has endpoints `.well-known/openid-configuration`
33+
and `.well-known/keys` that allow OIDC providers to validate JWTs minted
34+
by this secret engine.
35+
36+
## SPIFFE secrets engine API
37+
38+
The SPIFFE secrets engine has a full HTTP API. Refer to the
39+
[SPIFFE secrets engine documentation](/vault/api-docs/spiffe) for more details.

0 commit comments

Comments
 (0)