Repository navigation
v3.3: SAFs -> guidance for constants versus discoverability #5570
Description
This is a follow up to this comment #5447 (comment) which was left during the TDC call.
Some values, especially in the context of formalized security protocols, could be discovered at runtime through the protocol, and/or specified in the OAD as a constant from the SAF data structure.
An example of that is the GNAP as_url that can be discovered in the www-authenticate header in the 401 response, or specified in the OAD (based on the current proposal at time of writing).
After we spin the wheel on a couple of times on new SAFs (as @handrews has rightfully pointed out that we'll get better answers to those questions through a bit more experience on that new design approach), we should probably provide additional generic guidance that applies to all SAFs:
- outside of the OAS specification, for the people writing SAFs, when should a "field" that already can be discovered at runtime be available in the data structure as well?
- in the OAS specification, for users of the specification/SAFs: what to do when a value in the document contradicts a value discovered at runtime?
I hope this issue captures the 2 discussions on the topic accurately. And that it's articulate enough that when we revisit the issue in a couple of months we know what this is about :)
Activity
SensibleWood commentedon Oct 22, 2026
Just a couple of thoughts on the two bullets above.
To me this smacks of closed world vs. open world debates I've seen before and I think it needs some decent framing, because otherwise a SAF author could both "too much information" making that SAF heavy and harder to maintain but then also not enough so the result of using the SAF is not sufficiently determnistic. There needs to be guardrails on how much information to provide.
I think here to the existing discussions on JWTs. The JWT Payload needs to be well described, probably in a (ultimately) a Schema Object, but there is a bunch of stuff about JWTs that doesn't describe the shape of the object, and is embedded in the underlying JOSE RFCs. Does that stuff need repeating? For example, does a SAF need to say anything about the JWT Header for properties that are dynamic and defined by discovery, for example the allowed
algvalues repressented byid_token_signing_alg_values_supported?Can such information comfortably remain in the RFC/profile by reference, with no specific mention in the SAF, or if not what is the mechanism for providing enough information for a client to interpret the requirements?
I assume that an example of this, using the GNAP proposal par exemplar is the
as_uribeing defined in an OAD and then additionally being returned in the401?handrews commentedon Oct 23, 2026
Presumably, if you're defining
gnapAsUriin the Security Scheme Object, you do not expect to getas_uriback in a 401. But of course, APIs can do whatever they want a runtime, so we have to address that case. In this specific example, it's not because we expect people to configure that intentionally but it might happen despite that.Keep in mind that not everyone is using a profile. It has to be possible to configure everything manually and directly.
With JWTs and the JOSE header (in general, not just in OAuth/OIDC/GNAP), the OAD needs to provide enough information so that implementations can create them and verify them. So you need to know what encryption algorithms are supported, what claims are expected, and possibly something about public keys. It's fine if there's a profile that says which of these to use, but again, many people aren't using a well-defined profile. They're just doing stuff, and our JOSE support ought to work for any usage of JWTs, not just ones in a security context with a well-defined profile.