spring-projects / spring-projects/spring-security

Improve URI placeholders documentation

Open
#19,090 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

status: waiting-for-triage type: enhancement
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 the Host header. This documentation would outline the security tradeoffs of using {baseUrl} vs hardcoding a URI in situations where the Host header is not trusted. This might go in the Exploits section of the documentation.
  • Update the HttpFirewall documentation to demonstrate configuring an expected set of host headers
  • Update the Proxy configuration documentation to be in line with modern Boot configurations
  • Update both HttpFirewall and 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.