Arazzo and the OAS Link Object (and other overlaps and integrations)

[handrews]

Hi folks,
As we start planning for OAS v3.3, I'm looking at several proposals or complaints about the Link Object. Does Arazzo make any use of it? Is it redundant now that we have Arazzo? Or could it be useful, perhaps with some improvements?

I don't know that it would get prioritized for 3.3, but there's at least some conceptual overlap and it would be good to figure out if we ought to more-or-less deprecate the Link Object in favor of Arazzo.

[kevinduffey]

Arazzo doesn't use it that I know of. With Arazzo I don't see why it is needed any longer in the OAS spec. We have discussed this some time back as well and though it was a while ago I am pretty sure Arazzo does a lot more than Links do and is one of the primary reasons for the spec, ability to define workflow request chains.. but adds the ability to utilize requests across APIs so unlike Links it's not relegated to a single API description.
I'd also argue that deprecating it while pointing to the Arazzo spec would potentially alert those not aware of Arazzo to the spec. Maybe.

[frankkilcommins]

I can confirm that there's no use of the OAS Link Object within Arazzo. At one point we had discussed loose verbiage mentioning that Link Objects defined within a referenced OpenAPI Description may have influence on the workflow but as that was a little too ambiguous and because we could not determine a clear use case where both Arazzo and OAS Link Objects would be used in unison, we did included anything into Arazzo.

It's a good conversation to have and determine a path forward. I tend to agree with Kevin that it can help shine a light on where Arazzo can play an important role while also ensuring we done create unnecessary overlap between the specs.

[handrews]

@frankkilcommins @kevinduffey thanks, this helps! What about Callbacks? [EDIT: See #398 for callbacks] That is another workflow-ish thing in the OAS, but definitely a bit different (I can open a separate discussion if preferred, but I'm kind of making this a general OAS/Arazzo overlap discussion at the moment).

One use case I've been thinking of is as a fallback for implementing complex auth flows. We'd love to have elegant Security Scheme solutions for every possible form of auth. But even when those indicate that another specification such as OAuth2 or OIDC is to be used, there are often gaps in the steps that we don't document well.

It's occurred to me to wonder if it might make sense to allow documenting those steps as "normal" HTTP interactions (which is a fairly complex idea that may or may not be the right approach, but will be discussed in the OAS repo) and use Arazzo to document show the full authentication/authorization workflow.

Which brings up another thought- are there times when an OAD would want to reference an Arazzo document, instead of (or in addition to) the other way aroudn? Like... "if you want to use these endpoints, go look over here." That could be another way to draw attention to Arazzo.

[handrews]

@RomanHotsiy thanks for providing a counter-example, that's super-useful!

I don't expect that all flows could be described with OpenAPI/Arazzo today, but I do want to understand if whether it's something that might work with a few changes.

I looked over the "digest" auth scheme and I see two possible challenges — please let me know if I missed something!

1. There is a complex header structure involved for both WWW-Authenticate and Authorization (and the related Proxy- and -Info headers)
2. The construction of the response can be quite complex, involving pulling fields from the complex headers, unquoting them, and composing them into a different moderately complex string format, which is beyond Arazzo's current capabilities (and possibly beyond what is reasonable to add)

The first problem will be solved in 3.3, as we plan to define models for HTTP headers so that they can be thoroughly described by Schema Objects. In some cases this will be done directly, but with Authorization (and perhaps WWW-Authenticate, etc.) we will want to add modeling of the contents other than the scheme name to the type: http Security Scheme to avoid having to define case-insensitive auth schemes with JSON Schema, which does not handle case-insensitive validation well.

The second might require some extensions to Arazzo's Runtime Expressions to be able to pull things out of headers using the relevant Schema Object model. But it also needs to be able to construct the :-separated response string. The solution might be to include the response string format in the data model so that the Schema Obejct can model its pieces.

I'm definitely glossing over a lot of details to be hammered out, and there's no way to really evaluate this idea without seeing the data models that would be involved, and what possible runtime expression enhancements would be needed.

But this is how I'd go about supporting HTTP digest auth, at first glance. Thoughts and objections welcome!

[RomanHotsiy]

and possibly beyond what is reasonable to add

I agree with this ☝️. It's not just pulling and constructing strings, it's also running crypto (like md5 hash).

But to me it feels like like going one layer down. Using this logic, we could remove predefined authentication schemas from OpenAPI and model them with raw calls 🤷.

Yes, this approach will allow for some special auth schemas to be described but should we optimize for that?

I see the lack of flexibility for special use cases as a "soft power" that encourages folks to adopt open standards.

[handrews]

@RomanHotsiy thanks, you bring up some really worthwhile points I'd like to discuss further.

I see the lack of flexibility for special use cases as a "soft power" that encourages folks to adopt open standards.

I would agree with this if we were good at allowing folks to use the open standards, or had the volunteer bandwidth (or budget) to catch up. But we're not and we don't. Mostly I see people wanting to do that we would encourage using lower-level constructs is model standards-compliant security that Security Schemes don't support. Or don't support insufficient detail.

Yes, this approach will allow for some special auth schemas to be described but should we optimize for that?

We're going to have the ability to model headers no matter what, because it's a huge gap and there's a very long list of issues requesting such things. The only question is how much that gets used for authn/authz, and I think the word "optimize" is key here.

While I think it would be fine for tools to recognize certain low-level patterns as implementing optimizable auth flows, I would be against making that a requirement. If you want to manually model something, there's going to have to be a certain amount of "manual" work to use it. Which is why we really want to enhance (or replace) the Security Scheme concept. Again, if we had infinite resources, we'd just focus on Security Schemes and not even be having this conversation. Arazzo use of Security Schemes would require new techniques like the x-security extension that are aware of Security Schemes as distinct from normal endpoints.

So I don't think we should optimize low-level security configuration [although see further down about component libraries]. I think allowing it (leveraging things we will already support anyway, so minimal if any additional implementation requirements) gives people the opportunity to show what is in demand. Which helps us prioritize our limited resources for expanding Security Schemes.

But to me it feels like like going one layer down. Using this logic, we could remove predefined authentication schemas from OpenAPI and model them with raw calls 🤷.

Technically yes, but it would be verbose and messy. So far we've discussed two ways of this might get used:

• Some brave souls might actually fully model things at the low level. As noted above this wouldn't be automatically recognized as a security configuration or flow by tools, but it would still describe the necessary HTTP interactions. Again the only reason to consider this is that we'll have all the pieces anyway; we're just deciding whether to forbid using those pieces or allow them.
• Another option would be to publish an official component library including some low-level descriptions of standardized (strong agree with you on only encouraging standards) low-level security models. These could be used directly, probably with overlays to insert usage-specific bits. If we wanted to do something to make it clear that a standard component is in use, then we could potentially optimize those. They would basically be a poor person's Security Scheme. Doing so would require an addition to the OAS to recognize component usage, which is now transparent, and that has its own issues to consider.

it's also running crypto (like md5 hash).

I'm less concerned with this sort of thing as it is inherent in the format and therefore does not need to be modeled with Runtime Expressions or a Schema Object. For an example of what I mean, take a look at the suggested JSON Schema data model for application/jwt (it's the third example in the section). Note that the data model does not include the encryption or base64url encoding. It just models the data. We don't need to model formatting syntax or standardized encryption or encoding.

[frankkilcommins]

Appreciate the details and discussions here @handrews @RomanHotsiy @DmitryAnansky @kevinduffey. Just responding to the initial ping (as this slipped through the priority list last week).

What about Callbacks? That is another workflow-ish thing in the OAS, but definitely a bit different (I can open a separate discussion if preferred, but I'm kind of making this a general OAS/Arazzo overlap discussion at the moment).

I would prefer a separate discussion/issue on that topic. Part of the proposal for AsyncAPI will be adding features that make leveraging callbacks and/or webhooks as part of a workflow more manageable.

One use case I've been thinking of is as a fallback for implementing complex auth flows. We'd love to have elegant Security Scheme solutions for every possible form of auth. But even when those indicate that another specification such as OAuth2 or OIDC is to be used, there are often gaps in the steps that we don't document well.

It's occurred to me to wonder if it might make sense to allow documenting those steps as "normal" HTTP interactions (which is a fairly complex idea that may or may not be the right approach, but will be discussed in the OAS repo) and use Arazzo to document show the full authentication/authorization workflow.

During some of the earlier 1.0.0 work, there was representation from the OpenID Foundation within the working group, with the very intention of being able to leverage Arazzo to document the steps required to perform such interactions. We do need to dive into this and as seen by the x-security extension from the folks at Redocly, there's gaps to be closed to ensure we're expressive enough in this regard.

Happy to chime in on points above as needed.

[handrews]

@frankkilcommins I have filed #398 for the callbacks/webhooks discussion.