diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx new file mode 100644 index 0000000000..ebdaf2bf01 --- /dev/null +++ b/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: )` - The SPIFFE trust domain used by the + plugin. You can omit the `spiffe://` prefix. +- `profile` `(string: )` - 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: )` - 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: )` - 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: )` - 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: )` - 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: )` - The SPIFFE ID of the remote endpoint to connect to. +- `endpoint_url` `(string: )` - URL of an HTTPS server that can +provide the PEM encoded X.509 certificate. +- `bundle` `(string: )` - 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: )` - The unique name of the SPIFFE role you want to + update. + +### Request parameters + +- `display_name` `(string: "")` - The human-readable name for tokens +issued when authenticating against the role. Defaults to the value provided for +`name`. +- `workload_id_patterns` `(array: )` - 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: )` - 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: )` - 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. + + + diff --git a/content/vault/v1.21.x (rc)/content/docs/auth/spiffe.mdx b/content/vault/v1.21.x (rc)/content/docs/auth/spiffe.mdx new file mode 100644 index 0000000000..28b43d644e --- /dev/null +++ b/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 +``` + +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. diff --git a/content/vault/v1.21.x (rc)/data/api-docs-nav-data.json b/content/vault/v1.21.x (rc)/data/api-docs-nav-data.json index 3fb4dca26b..50e47ffdb1 100644 --- a/content/vault/v1.21.x (rc)/data/api-docs-nav-data.json +++ b/content/vault/v1.21.x (rc)/data/api-docs-nav-data.json @@ -378,6 +378,15 @@ "color": "neutral" } }, + { + "title": "SPIFFE", + "path": "auth/spiffe", + "badge": { + "text": "ENTERPRISE", + "type": "outlined", + "color": "neutral" + } + }, { "title": "TLS Certificates", "path": "auth/cert" diff --git a/content/vault/v1.21.x (rc)/data/docs-nav-data.json b/content/vault/v1.21.x (rc)/data/docs-nav-data.json index 57ea340139..55e86a6ac2 100644 --- a/content/vault/v1.21.x (rc)/data/docs-nav-data.json +++ b/content/vault/v1.21.x (rc)/data/docs-nav-data.json @@ -2656,6 +2656,15 @@ "color": "neutral" } }, + { + "title": "SPIFFE", + "path": "auth/spiffe", + "badge": { + "text": "ENT", + "type": "filled", + "color": "neutral" + } + }, { "title": "TLS Certificates", "path": "auth/cert"