Add spiffe secrets engine docs

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: <required>)` - 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: <required>)` - The unique name of the SPIFFE role you want to
+  update.
+
+### Request parameters
+
+- `template` `(string: <required>)` - 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: <required>)` - 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: <required>)` - 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.
+
+
+

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.