spring-projects / spring-projects/spring-security
Improve URI placeholders documentation
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 9.6k
- Forks
- 6.3k
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 52
Description
Spring Security supports URI placeholders such as {baseUrl}, {baseScheme}, {baseHost}, {basePort}, and {basePath} in OAuth 2.0 / OIDC client configuration, SAML 2.0 RelyingPartyRegistration, OIDC logout URLs, and related areas. These placeholders are resolved from the current HTTP request (via mechanisms such as UrlUtils.buildFullRequestUrl on Servlet), which makes configuration portable but introduces security considerations when the apparent request origin is not trustworthy (for example, spoofed Host or untrusted Forwarded / X-Forwarded-* headers).
It would be helpful to include in the documentation the security considerations around using URI placeholders so applications can make an informed decision about when to use them.
Some things that would be helpful:
- Add documentation that explains how
{baseUrl}, etc. are derived, including that they are built using theHostheader. This documentation would outline the security tradeoffs of using{baseUrl}vs hardcoding a URI in situations where theHostheader is not trusted. This might go in the Exploits section of the documentation. - Update the
HttpFirewalldocumentation to demonstrate configuring an expected set of host headers - Update the Proxy configuration documentation to be in line with modern Boot configurations
- Update both
HttpFirewalland Proxy configuration documentation to refer back to the new documentation about URI placeholders. - Update RelyingPartyRegistration documentation to outline which properties support placeholders and what each property is used for during login.
- Update the OAuth 2.0, OIDC, and SAML documentation to point to this new documentation wherever URI placeholders are a relevant topic of conversation.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked HttpFirewall and Proxy configuration documentation, then review the RelyingPartyRegistration, OAuth 2.0, OIDC, and SAML sections named in the issue. Document how URI placeholders are derived and their Host-header security tradeoffs, update the requested configuration guidance, and add cross-references wherever placeholders are discussed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation, security
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 50/100