Add SPIFFE auth plugin docs #1006
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Vercel Previews Deployed
|
Broken Link CheckerNo broken links found! 🎉 |
schavis
requested changes
Oct 6, 2025
Comment on lines
88
to
90
| When using a profile that fetches the trust bundle from a remote endpoint, the trust | ||
| bundle is cached locally and is refreshed periodically. Refresh intervals are calculated | ||
| based on the bundle's refresh hint (if provided) or a default of 1 hour. |
There was a problem hiding this comment.
Suggested change
| When using a profile that fetches the trust bundle from a remote endpoint, the trust | |
| bundle is cached locally and is refreshed periodically. Refresh intervals are calculated | |
| based on the bundle's refresh hint (if provided) or a default of 1 hour. | |
| 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. |
Style correction: write in active voice, avoid possessives
Folded in the refresh mechanics discussion from below
Comment on lines
92
to
97
| If an immediate refresh is required, call the [configuration endpoint](/vault/api-docs/auth/spiffe#create-configuration) | ||
| with an empty payload to force a refresh. | ||
|
|
||
| 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. The active node | ||
| on Performance replica clusters will fetch and refresh the trust bundle independently. |
There was a problem hiding this comment.
Suggested change
| If an immediate refresh is required, call the [configuration endpoint](/vault/api-docs/auth/spiffe#create-configuration) | |
| with an empty payload to force a refresh. | |
| 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. The active node | |
| on Performance replica clusters will 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). |
Comment on lines
99
to
100
| Details on the fetched trust bundle, including the last refresh time and the | ||
| refresh interval are available via the [read configuration endpoint](/vault/api-docs/auth/spiffe#read-configuration). |
There was a problem hiding this comment.
Suggested change
| Details on the fetched trust bundle, including the last refresh time and the | |
| refresh interval are available via the [read configuration endpoint](/vault/api-docs/auth/spiffe#read-configuration). |
Folded into the paragraph above
| Details on the fetched trust bundle, including the last refresh time and the | ||
| refresh interval are available via the [read configuration endpoint](/vault/api-docs/auth/spiffe#read-configuration). | ||
|
|
||
| ### Load Balancing / Proxying Consideration |
There was a problem hiding this comment.
Suggested change
| ### Load Balancing / Proxying Consideration | |
| ## Load balancing and proxying consideration |
Style correction: use sentence case for headers
Comment on lines
104
to
112
| If the Vault server is fronted by a reverse proxy or load balancer, TLS is | ||
| terminated before Vault. In that case the proxy must provide the validated | ||
| client certificate via header, and [configured in the Vault configuration's | ||
| listener stanza](/vault/docs/configuration/listener/tcp#tcp-listener-parameters). | ||
|
|
||
| Configure the listener with the header name that your load balancer provides. | ||
| In this mode, the security of authentication depends on the load balancer performing | ||
| full TLS verification to the client, and that the connection between the load | ||
| balancer and Vault is secured, ideally with Mutual TLS. |
There was a problem hiding this comment.
Suggested change
| If the Vault server is fronted by a reverse proxy or load balancer, TLS is | |
| terminated before Vault. In that case the proxy must provide the validated | |
| client certificate via header, and [configured in the Vault configuration's | |
| listener stanza](/vault/docs/configuration/listener/tcp#tcp-listener-parameters). | |
| Configure the listener with the header name that your load balancer provides. | |
| In this mode, the security of authentication depends on the load balancer performing | |
| full TLS verification to the client, and that the connection between the load | |
| balancer and Vault is secured, ideally with Mutual TLS. | |
| 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. |
Style correction: write in active voice, make complex lists easy to scan
Co-authored-by: Sarah Chavis <[email protected]>
Co-authored-by: Sarah Chavis <[email protected]>
schavis
reviewed
Oct 7, 2025
|
|
||
| Fetch a SPIFFE bundle in JWKS format from a remote HTTPS endpoint. If using a SPIRE server, this will work with | ||
| a SPIRE Federation API endpoint of type `https_web`. | ||
|
|
There was a problem hiding this comment.
Okay. Let's use the same field descriptions then
Co-authored-by: Sarah Chavis <[email protected]>
schavis
reviewed
Oct 7, 2025
schavis
approved these changes
Oct 7, 2025
Co-authored-by: Sarah Chavis <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Initial stab at adding the SPIFFE auth plugin docs.