From ac0ba55c0a5bf60b1da04e4139bbcc51518b804e Mon Sep 17 00:00:00 2001 From: ncabatoff Date: Thu, 30 Oct 2025 15:45:29 -0400 Subject: [PATCH 1/2] Add spiffe secrets engine docs --- .../content/api-docs/secret/spiffe.mdx | 190 ++++++++++++++++++ .../v1.22.x/content/docs/secrets/spiffe.mdx | 39 ++++ 2 files changed, 229 insertions(+) create mode 100644 content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx create mode 100644 content/vault/v1.22.x/content/docs/secrets/spiffe.mdx diff --git a/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx b/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx new file mode 100644 index 000000000..655a6b15d --- /dev/null +++ b/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx @@ -0,0 +1,190 @@ +--- +layout: api +page_title: SPIFFE - Secrets engines - HTTP API +description: This is the API documentation for the Vault SPIFFE secrets engine. +--- + +# SPIFFE secrets engine (API) + +Use the SPIFFE plugin to mint SPIFFE JWT-SVIDs. The example code below assumes +you mounted the SPIFFE plugin at `/spiffe`. Since it is possible to enable +secrets engines at any location, please update your API calls accordingly. + +## Create configuration + +Configure the SPIFFE trust domain for the plugin. + +| Method | Path | +|:-------|:----------------------| +| `POST` | `/spiffe/config` | + +### Request parameters + +- `trust_domain` `(string: )` - The SPIFFE trust domain used by the + plugin. You can omit the `spiffe://` prefix. +- `bundle_refresh_hint` `(int or time string: "1h")` - The value to put as the refresh hint in trust bundles we publish. +May not exceed key_lifetime/10. +- `key_lifetime` `(int or time string: "24h")` - How often to generate a new signing key. Uses duration format strings. +- `jwt_issuer_url` `(string: optional)` - The base URL to use for JWT issuer claims (`iss`), including + `https://` schema, host, and optional port. Must be reachable by whatever systems consume the JWTs. + By default it will be the vault cluster's api_addr. The mount path and issuer endpoint will be appended to this value. +- `jwt_signing_algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default), + RS384, RS512, ES256, ES384, ES512. +- `jwt_oidc_compatibility_mode` `(bool: false)` - When set true, attempts to generate JWT SVIDs will fail if the resulting + SPIFFEID exceeds 255 chars, the limit for JWT sub claims in OIDC. + +### Sample payload + +```json +{ + "trust_domain": "example.org", + "bundle_refresh_hint": "30m", + "key_lifetime": "12h" +} +``` + +## Read configuration + +Fetch the SPIFFE configuration details. + +| Method | Path | +|:-------|:----------------------| +| `GET` | `/spiffe/config` | + +### Request parameters + +None. + +### Sample response + +```json +{ + "bundle_refresh_hint": "3600", + "jwt_issuer_url": "", + "jwt_oidc_compability_mode": false, + "jwt_signing_algorithm": "RS256", + "key_lifetime": "86400", + "trust_domain": "example.org" +} +``` + +## Create role + +Create or update a named role that specifies the content of JWTs. + +| Method | Path | +|:-------|:--------------------------| +| `POST` | `/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to + update. + +### Request parameters + +- `template` `(string: )` - The template string to use for generating tokens. This may be in + stringified JSON or base64 format. +- `ttl` `(int or time string: "5m")` - TTL of the tokens generated against the role. Uses duration format strings. + TTLs of generated tokens will be capped by the lifespan of the current signing key. +- `use_jti_claim` `(bool: false)` - If true, the jti claim will be included in JWTs, which may impact + their reusability. + +Roles define a template in much the same way as [identity tokens](../identity/identity-token). As with identity tokens, some claims cannot be +overridden by the template and are populated by the secrets engine: + +- `iss`: Issuer URL is populated based on the global config setting jwt_issuer_url +- `aud`: Audience is populated by the JWT minting endpoint argument +- `iat`: Time of issue +- `exp`: Expiration time for the token (iat + ttl) +- `jti`: UUID that helps for audit trails and preventing replay attacks (rfc7519), present only if the role setting + `use_jti_claim` is true + +In addition to these standard claims, the following claim will be included to assist in provenance: +- `vault: {entity: {id: ENTITY_ID}}` +Here the entity id is that of the Vault client. + +Unlike with identity tokens, `sub` can (and must) be specified. This is either the SPIFFEID of the JWT SVID, or +the path part of a SPIFFEID, in which case the secrets engine will prepend `spiffe://` and the configured trust domain. +Role creation will fail if the parsed template doesn't have a sub claim. SVID minting will fail if the expanded template +isn't a valid SPIFFEID, or doesn't have the configured trust domain. + +### Sample payload + +```json +{ + "template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"" +} +``` + +## Read role + +Read the named SPIFFE role. + +| Method | Path | +|:-------|:--------------------------| +| `GET` | `/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to + read. + +### Sample response + +```json +{ + "template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"", + "ttl": "300", + "use_jti_claim": false +} +``` + +## Delete role + +Delete the named SPIFFE role. + +| Method | Path | +|:---------|:--------------------------| +| `DELETE` | `/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to delete. + +## List roles + +List the names of all SPIFFE roles. + +| Method | Path | +|:-------|:--------------------| +| `LIST` | `/spiffe/role` | + +### Request parameters + +None. + +### Sample response + +```json +{ + "keys": [ + "example-role" + ] +} +``` + +## Mint JWT token + +Creates and returns a JWT token based on the role's template, using JWT Compact Serialization format. + +| Method | Path | +|:-------|:---------------------| +| `POST` | `/spiffe/role/:name/mintjwt` | + +### Request parameters + +- `audience` `(string: "")` - The value to use for the `aud` claim in the JWT token. + + + diff --git a/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx b/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx new file mode 100644 index 000000000..8e82a8914 --- /dev/null +++ b/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx @@ -0,0 +1,39 @@ +--- +layout: docs +page_title: SPIFFE secrets engine +description: >- + The SPIFFE secrets engine allows users to mint SPIFFE JWT-SVIDs +--- + +# SPIFFE secrets engine + +@include 'alerts/enterprise-only.mdx' + +The `spiffe` secrets engine allows for minting SPIFFE JWT-SVIDS using a +template that can interpolate identity information about the requesting entity. +These JWTs are OIDC-compatible and so can also be used in the same way +as JWT tokens minted using the identity engine. + +## Configuration + +Each SPIFFE backend instance has a single trust domain. Roles are used to +define templates that determine the claims in the minted JWTs. + +## Integrate with SPIRE + +The SPIFFE secrets engine has an endpoint `trust_bundle/web` that serves +the trust bundle. This can be used by other systems that implement SPIFFE +federation, e.g. [SPIRE](https://spiffe.io/spire/) or another Vault cluster +running the [SPIFFE auth method.](../../auth/spiffe), in order to fetch +the public keys needed to validate JWTs minted by this secret engine. + +## Integrate with OIDC + +The SPIFFE secrets engine has endpoints `.well-known/openid-configuration` +and `.well-known/keys` that allow OIDC providers to validate JWTs minted +by this secret engine. + +## SPIFFE secrets engine API + +The SPIFFE secrets engine has a full HTTP API. Refer to the +[SPIFFE secrets engine documentation](/vault/api-docs/spiffe) for more details. From bb5cbf33ee8a7a9758dffb277a29d95bf498b5ea Mon Sep 17 00:00:00 2001 From: Nick Cabatoff Date: Mon, 3 Nov 2025 11:47:52 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Victor Rodriguez --- content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx | 2 +- content/vault/v1.22.x/content/docs/secrets/spiffe.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx b/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx index 655a6b15d..5ec7af785 100644 --- a/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx +++ b/content/vault/v1.22.x/content/api-docs/secret/spiffe.mdx @@ -134,7 +134,7 @@ Read the named SPIFFE role. ```json { - "template": "\"sub\": \"spiffe://example.com/sales/ {{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"", + "template": "\"sub\": \"spiffe://example.com/sales/{{identity.entity.aliases.auth_gcp_e3de7def.custom_metadata.spiffe_workload_id}}\"", "ttl": "300", "use_jti_claim": false } diff --git a/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx b/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx index 8e82a8914..62f80bade 100644 --- a/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx +++ b/content/vault/v1.22.x/content/docs/secrets/spiffe.mdx @@ -9,7 +9,7 @@ description: >- @include 'alerts/enterprise-only.mdx' -The `spiffe` secrets engine allows for minting SPIFFE JWT-SVIDS using a +The `spiffe` secrets engine allows for minting [SPIFFE](https://spiffe.io/) JWT-SVIDS using a template that can interpolate identity information about the requesting entity. These JWTs are OIDC-compatible and so can also be used in the same way as JWT tokens minted using the identity engine. @@ -24,7 +24,7 @@ define templates that determine the claims in the minted JWTs. The SPIFFE secrets engine has an endpoint `trust_bundle/web` that serves the trust bundle. This can be used by other systems that implement SPIFFE federation, e.g. [SPIRE](https://spiffe.io/spire/) or another Vault cluster -running the [SPIFFE auth method.](../../auth/spiffe), in order to fetch +running the [SPIFFE auth method](../../auth/spiffe), in order to fetch the public keys needed to validate JWTs minted by this secret engine. ## Integrate with OIDC