Add SPIFFE auth plugin docs

content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx

@@ -0,0 +1,286 @@
+---
+layout: api
+page_title: SPIFFE - Auth Methods - HTTP API
+description: This is the API documentation for the Vault SPIFFE authentication method.
+---
+
+# SPIFFE auth method (API)
+
+Use the SPIFFE plugin to support authentication with JWT or x.509 based SPIFFE
+SVIDs. The example code below assumes you mounted the SPIFFE plugin at
+`/auth/spiffe`. Since it is possible to enable auth methods at any location,
+please update your API calls accordingly.
+
+## Create configuration
+
+Configure or refresh the SPIFFE trust domain and associated trust bundle for the
+plugin. To refresh an existing cached bundle, call the endpoint with an empty
+payload. 
+
+If you use profiles that fetch the trust bundle from a remote endpoint, Vault
+immediately fetches a trust bundle when you create the configuration unless you
+set `defer_bundle_fetch` to `true`. If the initial fetch fails, Vault returns an
+error and rolls back any configuration changes.
+
+| Method | Path                  |
+|:-------|:----------------------|
+| `POST` | `/auth/spiffe/config` |
+
+### Request parameters
+
+- `trust_domain` `(string: <required>)` - The SPIFFE trust domain used by the
+  plugin. You can omit the `spiffe://` prefix.
+- `profile` `(string: <required>)` - The profile to use to fetch the trust bundle, see profile section below
+for associated parameters based on the selected profile. Valid values are `static`,
+- `profile` `(string: <required>)` - Set the profile type and fetch mechanism
+  for the profile used to fetch the trust bundle. Must be one of:
+    - `https_spiffe_bundle` - fetch the trust bundle in JWKS format from a
+      SPIFFE endpoint.
+    - `https_web_bundle` - fetch the trust bundle in JWKS format from an HTTPS
+      endpoint.
+    - `https_web_pem` - fetch a valid X.509 certificate as the trust bundle
+      from an HTTPS endpoint.
+    - `static` - use the trust bundle explicilty configured in the profile
+      definition.
+- `audience` `(array: [])` - A list of allowed audience values for JWT based
+  SVIDs. Vault rejects any JWT-based SVIDS not provided in the audience list.
+  Leave `audience` empty to deny all JWT-based SVIDS.
+- `defer_bundle_fetch` `(bool: false)` - Tells Vault not to fetch the remote
+  trust bundle to validate the configuration. For example, you can set
+  `defer_bundle_fetch` to `true` when you need to update your Vault
+  configuration before the remote endpoint is available.
+
+#### Profile parameters
+
+In addition to the common request parameters, you must set the following profile-specific parameters based on the value of `profile`.
+
+##### Static profile (`static`)
+
+Provide the trust bundle directly as part of the configuration.
+
+- `bundle` `(string: <required>)` - A PEM encoded X.509 certificate or a JWKS document following
+the SPIFFE Trust Domain and Bundle specification.
+
+##### Remote HTTPS Web PEM profile (`https_web_pem`)
+
+Provide HTTPS connection details so Vault can fetch an X.509 certificate
+to use as a trust bundle.
+
+- `endpoint_url` `(string: <required>)` - URL of an HTTPS server that can
+  provide the PEM encoded X.509 certificate.
+- `endpoint_root_ca_truststore_pem` `(string: "")` - A PEM encoded X.509
+  certificate Vault can use as a root CA to validate the TLS certificate provided
+  by the remote server. Leave `endpoint_root_ca_truststore_pem` unset to use the
+  system root CAs.
+
+##### Remote HTTPS Web Bundle profile (`https_web_bundle`)
+
+Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS
+format from a remote server. To use the remote HTTPS web bundle profile with a
+SPIRE server, the server must support a SPIRE Federation API endpoint of type
+`https_web`.
+
+- `endpoint_url` `(string: <required>)` - URL of an HTTPS server that can
+  provide the PEM encoded X.509 certificate.
+- `endpoint_root_ca_truststore_pem` `(string: "")` - A PEM encoded X.509
+  certificate Vault can use as a root CA to validate the TLS certificate provided
+  by the remote server. Leave `endpoint_root_ca_truststore_pem` unset to use the
+  system root CAs.
+
+##### Remote HTTPS SPIFFE Bundle profile (`https_spiffe_bundle`)
+
+Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS
+format from a remote SPIFFE endpoint. To use the remote HTTPS SPIFFE profile
+with a SPIRE server, the server must support a SPIRE Federation API endpoint of
+type `https_spiffe`.
+
+- `endpoint_spiffe_id` `(string: <required>)` - The SPIFFE ID of the remote endpoint to connect to.
+- `endpoint_url` `(string: <required>)` - URL of an HTTPS server that can
+provide the PEM encoded X.509 certificate.
+- `bundle` `(string: <required>)` - A SPIFFE bundle in JKWS format that Vault
+  can use as a trust anchor to validate the TLS certificate from the SPIFFE
+  endpoint.
+
+### Sample payload
+
+```json
+{
+  "trust_domain": "example.org",
+  "profile": "https_web_bundle",
+  "endpoint_url": "https://spire.example.org",
+  "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
+  "audience": ["vault"]
+}
+```
+
+## Read configuration
+
+Fetch the SPIFFE configuration details and relevant metadata about the currently
+cached trust bundle.
+
+| Method | Path                  |
+|:-------|:----------------------|
+| `GET`  | `/auth/spiffe/config` |
+
+### Request parameters
+
+None.
+
+### Sample response
+
+```json
+{
+  "cached_bundle_config_version": 1,
+  "cached_bundle_fetched_at": "2025-09-18T14:02:21.730308-04:00",
+  "cached_bundle_refresh_hint": "15m0s",
+  "cached_bundle_sequence_number": 11,
+  "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
+  "endpoint_url": "https://192.168.1.65:8443",
+  "profile": "https_web_bundle",
+  "trust_domain": "spiffe://test.dadgarcorp.org",
+  "version": 1
+}
+```
+
+## Create role
+
+Create or update a named role that maps SPIFFE IDs to Vault policies.
+
+Different roles may not have the same workload ID patterns. Vault uses standard
+[policy priority matching](vault/docs/concepts/policies#priority-matching) logic
+to determine the appropriate role when there  are overlapping patterns across
+different roles (e.g. role1 has `team1/*` and role2 has `team1/service1`).
+
+| Method | Path                       |
+|:-------|:---------------------------|
+| `POST` | `/auth/spiffe/role/:name` |
+
+### Path parameters
+
+- `name` `(string: <required>)` - The unique name of the SPIFFE role you want to
+  update.
+
+### Request parameters
+
+- `display_name` `(string: "<name>")` - The human-readable name for tokens
+issued  when authenticating against the role. Defaults to the value provided for
+`name`.
+- `workload_id_patterns` `(array: <required>)` - A comma separated list of
+  patterns that match an incoming workload ID associated with the SPIFFE role. 
+  You can find the workload ID by stripping the trust domain prefix and slash
+  separator from the associated SPIFFE ID. You can use the following special
+  characters with the workload ID:
+
+  - `*` - matches to any number of characters at the end of an ID to perform
+    prefix matching
+  - `+` - matches to any number of characters within a single path segment to
+    perform wildcard matching.
+
+@include 'tokenfields.mdx'
+
+### Sample payload
+
+```json
+{
+  "workload_id_patterns": ["service1", "team1/*", "team2/+/service1"],
+  "display_name": "example-role",
+  "token_policies": ["spiffe-service1"]
+}
+```
+
+## Read role
+
+Read the named SPIFFE role.
+
+| Method | Path                      |
+|:-------|:--------------------------|
+| `GET`  | `/auth/spiffe/role/:name` |
+
+### Path parameters
+
+- `name` `(string: <required>)` - The unique name of the SPIFFE role you want to
+  read.
+
+### Sample response
+
+```json
+{
+  "alias_metadata": {},
+  "display_name": "example-role",
+  "name": "example-role",
+  "token_bound_cidrs": [],
+  "token_explicit_max_ttl": 0,
+  "token_max_ttl": 0,
+  "token_no_default_policy": false,
+  "token_num_uses": 0,
+  "token_period": 0,
+  "token_policies": [
+    "spiffe-service1"
+  ],
+  "token_ttl": 0,
+  "token_type": "default",
+  "workload_id_patterns": [
+    "service1",
+    "team1/*",
+    "team2/+/service1"
+  ]
+}
+```
+
+## Delete role
+
+Delete the named SPIFFE role.
+
+| Method   | Path                      |
+|:---------|:--------------------------|
+| `DELETE` | `/auth/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` | `/auth/spiffe/role` |
+
+### Request parameters
+
+None.
+
+### Sample response
+
+```json
+{
+  "keys": [
+    "example-role"
+  ]
+}
+```
+
+## Login with SPIFFE ID
+
+Authenticate a client using a SPIFFE JWT or x.509 SVID. To use JWT, set the SVID
+in the `Authorization` header as the bearer token and set the `Authorization`
+header as a passthrough request header in the SPIFFE backend.
+
+| Method | Path                 |
+|:-------|:---------------------|
+| `POST` | `/auth/spiffe/login` |
+
+### Request parameters
+
+- `role` `(string: "")` - The name of the role to use for authentication. Leave
+  `role` unset to have Vault iterate over all configured roles.
+- `type` `(string: "auto")` - Set the SVID source for authentication. Must be one of:
+  - `auto` - use JWT SVIDs if provided, otherwise use SVIDs from the peer x.509
+    certificate.
+  - `cert` - only use SVIDs from x.509 certificates.
+  - `jwt` - only use JWT SVIDs.
+
+
+

content/vault/v1.21.x (rc)/content/docs/auth/spiffe.mdx

@@ -0,0 +1,111 @@
+---
+layout: docs
+page_title: SPIFFE - Auth Methods
+description: >-
+  The SPIFFE auth method allows users to authenticate with
+  Vault using JWT and X.509 based SPIFFE SVIDs
+---
+
+# SPIFFE auth method
+
+@include 'alerts/enterprise-only.mdx'
+
+The `spiffe` auth method lets you configure authentication using JWT or x.509
+based SPIFFE SVIDs whose trust can be rooted within a configured trust bundle.
+
+To use the SPIFFE plugin with x.509 SPIFFE IDs, you must have `tls_disable` and
+`tls_disable_client_certs` set to false in your Vault configuration to allow
+the certificates through TLS.
+
+## Configuration
+
+Each SPIFFE backend instance has a single trust domain and an associated trust
+bundle and a role-level configuration that maps SPIFFE workload IDs to Vault
+token policies. Vault accepts trust bundles provided as part of the
+configuration or fetched from a remote endpoint over HTTPS.
+
+## Integrate with SPIRE
+
+If you use [SPIRE](https://spiffe.io/spire/) to issue SPIFFE SVIDs, you can
+configure Vault to fetch the trust bundle directly from the SPIRE Federation
+API if you use `https_web` and `https_spiffe` Federation endpoints.
+
+
+## JWT SPIFFE SVID requirements
+
+To use JWT based SPIFFE SVIDs, you must include the `Authorization` header
+in the set of passthrough request headers for the SPIFFE plugin so clients can
+provide the SVID in the `Authorization` header as a `Bearer` token. For example:
+
+```text
+Authorization: Bearer <svid-jwt>
+```
+
+When enabling the SPIFFE auth method, you can specify the passthrough
+Use the `-passthrough-request-headers` flag when you enable or tune the SPIFFE
+plugin to add `Authorization` to the set of allowed passthrough headers.
+
+For example, to configure the headers when you mount the plugin, use
+`-passthrough-request-headers` with `vault auth enable`:
+```shell
+$ vault auth enable -passthrough-request-headers="Authorization" spiffe
+```
+
+Or, to configure the headers on an existing mount, use
+`-passthrough-request-headers` with `vault auth tune`:
+
+```shell
+$ vault auth tune -passthrough-request-headers="Authorization" spiffe
+```
+
+### Provide valid audience values
+
+When using JWT based SPIFFE SVIDs, you must configure the plugin with a list of
+allowable audience values and clients must set the
+[audience](/vault/api-docs/auth/spiffe#audience) parameter with one of the
+appropriate values. Vault allows any client with a matching element to
+authenticate. If the list of allowable values is empty, Vault denies all JWT
+based SVIDS.
+
+## Supported trust bundle formats
+
+To use JWT and x.509 based SPIFFE IDs, the trust bundle must contain the X.509
+certificate(s) and JWK key(s) within a JWKS document for static and fetched bundles.
+
+To use a PEM encoded X.509 certificate, the trust bundle must provide a x.509
+based SPIFFE ID.
+
+## Refreshing remote trust bundles
+
+Vault caches trust bundles fetched from remote endpoints and refreshes the
+bundle periodically based on the provided refresh hint. If the bundle does not
+provide a refresh hint, Vault uses a default refresh interval of 1 hour.
+
+The active node within a Vault cluster performs the initial fetch and subsequent
+refreshes on the trust bundle on behalf of all nodes in the cluster. But all
+active nodes on Performance replica clusters fetch and refresh the trust
+bundle independently.
+
+You can force an immediate refresh by calling the
+[configuration endpoint](/vault/api-docs/auth/spiffe#create-configuration)
+with an empty payload and read the details about a fetched trust bundle,
+including the last refresh time and calculated refresh interval by calling the
+[read configuration endpoint](/vault/api-docs/auth/spiffe#read-configuration).
+
+## Load balancing  and proxying consideration
+
+TLS terminates before client requests reach Vault when you use a reverse proxy
+or load balancer as your Vault server fronted. As a result, you must:
+
+1. Configure your frontend to provide the validated client certificate in the
+   request header.
+1. [Configure your Vault listener](/vault/docs/configuration/listener/tcp#tcp-listener-parameters)
+   to accept the header provided by the frontend.
+1. Ensure your frontend performs full TLS verification to the client to provide
+   proper authentication security.
+1. Ensure a secure connection between your frontend and Vault, ideally with
+   Mutual TLS.
+
+## SPIFFE plugin API
+
+The SPIFFE auth method has a full HTTP API. Refer to the [SPIFFE auth API documentation](/vault/api-docs/auth/spiffe) for more details.