Missing informaiton for mutualTLS in v3.1.0 Spec

[philsturgeon]

Just noticed there's no information about mutualTLS in the spec other than that it exists as a valid type.

[MikeRalphson]

As intended. See lengthy discussions in #1004 - note specification extensions are allowed also. What fields do you think are missing?

[philsturgeon]

I don’t know if it needs any fields but maybe an example or something. I’m just saying I have no idea how it works.

[MikeRalphson]

It's just a hint to consoles / SDKs (and all other use-cases) that a client certificate must be obtained in some way and presented in the TLS connection.

[philsturgeon]

Right, but unless we want to continue the years old OAI trend of making PR comments part of the spec/docs, could we consider making the specs have some information on how mutualTLS works? 😆

[MikeRalphson]

unless we want to continue the years old OAI trend of making PR comments part of the spec/docs

Can you run that sentence by me one more time? I totally don't get it.

[philsturgeon]

It was a funny joke about how lots and lots and lots of what we’ve recently had to clarify in the spec (3.0.x) was all “the spec is t clear but Darrel said this in an issue a few years ago” or “this issue says X and that pull request says Y but the spec doesn’t say anything so which is right”.

I’d like to try and get away from that.

Put another way: You’re kind to try and help me understand what mutualTLS might look like, but we could probably put an example in the spec, as we’ve put other security examples in the spec.

On Sat, Feb 20, 2021 at 08:54, Mike Ralphson notifications@github.com wrote:

unless we want to continue the years old OAI trend of making PR comments part of the spec/docs

Can you run that sentence by me one more time? I totally don't get it.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[MikeRalphson]

“the spec is clear but Darrel said this in an issue a few years ago” or “this issue says X and that pull request says Y but the spec doesn’t say anything so which is right”. I’d like to try and get away from that.

I see either @Relequestual's proposed use of Architectural Decision Records over at JSON Schema, or the publishing of some "technical notes" as a good way to capture additional information about how the sausage was made, without bloating the spec itself.

I'm still struggling to see what an example would add above the stated support for the type that's already in the spec. But, as ever, PRs for discussion are always welcomed!

[philsturgeon]

I'm not looking for anything complex, just consistency. We show samples for other security schemes so lets add a sample for this one too. https://github.com/OAI/OpenAPI-Specification/pull/2625

[cy6org]

I'm attempting to use the securityScheme type mutualTLS. Where/how to I provide the cert or cert chain I need in order to authenticate? The example (requested in this thread) should illustrate this detail.

If it's already documented and my weak google-foo can't find it, please advise.

[shriduttkothari]

I'm also attempting to use the securityScheme type mutualTLS.

But don't know how to use it, thee is not documentation available, and no sample or example avaiable.

Kindly help if anyone knows how to use securityScheme type mutualTLS!!

[LasneF]

given the subject is quite old , given a basic exemple has been provided in the merge request . Meaning you advertise that the API requires MutualTLS to be used . given that for mutualTLS there must be direct and long communication between parties, to me the description field is good enough to details what is required

[lornajane]

Thanks @LasneF ! Part of the problem here is that the example is in an unreleased spec version, but I think we do have the example requested, so I'll close the issue.