Clarify dual use of iss parameter: SMART launch URL vs RFC 9207

[dionmcm]

Summary

Clarifies the dual use of the iss query parameter in SMART App Launch and OAuth 2.0 authorization responses (RFC 9207).

• In SMART launch URLs, iss represents the FHIR server base URL
• In OAuth authorization responses, iss (per RFC 9207) represents the authorization server issuer

This PR adds a small clarification to distinguish these contexts and prevent misinterpretation in client implementations.

---

Problem

SMART App Launch and RFC 9207 both define a query parameter named iss, but with different meanings at different stages of the flow:

• SMART App Launch (launch request)
  iss = FHIR server base URL

• RFC 9207 (authorization response)
  iss = authorization server issuer (to mitigate mix-up attacks)

With increasing adoption of RFC 9207 (e.g. Keycloak ≥23, FAPI 2.0), clients may receive an iss parameter on the OAuth callback and incorrectly interpret it as the FHIR server base URL. This can lead to:

• incorrect FHIR endpoint selection
• broken token exchange flows
• workarounds that disable RFC 9207 protections

---

Proposed Change

This PR introduces minimal, targeted clarifications:

1. Launch section
   Adds a note clarifying that iss in the launch URL refers to the FHIR server base URL.

2. Authorization response handling
   Adds normative guidance that:

   • iss in the authorization response SHALL be interpreted as the RFC 9207 authorization server issuer
   • clients MAY validate it against the expected authorization server
   • clients SHALL NOT use it to determine the FHIR server base URL

3. (Optional) Security considerations
   Encourages validation of iss per RFC 9207 to mitigate mix-up attacks.

---

Rationale

• The two uses of iss occur in different phases of the SMART flow (launch vs callback)
• Clarifying this avoids ambiguity without breaking existing behaviour
• Enables safe adoption of RFC 9207 protections rather than encouraging them to be disabled
• Provides clear guidance for client libraries (e.g. smart-on-fhir/client-js)

---

Backwards Compatibility

This is a non-breaking clarification only.
No changes to existing parameter definitions or behaviour are required.

---

References

• SMART App Launch specification
• RFC 9207: OAuth 2.0 Authorization Server Issuer Identification
• FAPI 2.0 Security Profile (requires RFC 9207 support)

---

Notes

This PR was prompted by issues observed when RFC 9207 support is enabled (e.g. Keycloak ≥23), where the iss parameter in authorization responses was misinterpreted smart-on-fhir/client-js.

Following a Zulip conversation, this proposal reflects the suggested approach of distinguishing launch vs callback handling (e.g. based on the presence of an authorization code parameter), and clarifies the intended meaning of iss in each context.

The goal here is simply to make this behaviour explicit for implementers, avoid the need for workarounds (such as disabling RFC 9207), and support safe adoption of its protections.

This is the subject of FHIR-56141 Disambiguate iss in SMART flows with RFC 9207.

Very happy for this to be refined, reworked, or redirected to better align with the spec.