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..5ec7af785 --- /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..62f80bade --- /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](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. + +## 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.