Custom Security Schemes

[ioggstream]

This PR

Added support for additional security schemes by adding a "custom" value to the security scheme type enumeration and a customType field to distinguish between custom schemes.

Note

Split from #1736

@cmheazel pls review.

[MikeRalphson]

Comments as above. Otherwise LGTM.

[MikeRalphson]

Instead of shall, can we use MUST or SHOULD as deemed appropriate. Can we also say Validating implementations as not all tooling is or has a validator. Should securitySchemeType be a link?

[ioggstream]

1- type REQUIRED when securityScheme: custom
2- specificationExtension is RECOMMENDED
3- no changes about type to be a link. In that case, it should be url or uri ?

[cmheazel]

Implementations SHALL accept "custom" as a valid value. Otherwise they would throw an error when processing a valid OAS document. Requiring that the customType field is present and populated is consistent with the handling of other security scheme specific fields. That doesn't mean that the implementation has to do anything with the values, just check that something is there.

[cmheazel]

Re: customType as a uri. The current text says that the values for the customType field are not controlled. If they are not controlled, then limiting the values to a URI is an unnecessary restriction. However, if we are open to adding custom security schemes to the OAS register----

[ioggstream]

Implementations SHALL accept "custom" as a valid value.
Otherwise they would throw an error when processing a valid OAS document.

iiuc SHALL/SHOULD means that a validating implementation may not accept custom. Am I wrong?

Requiring that the customType field is present and populated
is consistent with the handling of other security scheme specific fields.

So 1) is fine, right?

That doesn't mean that the implementation has to do anything with the values, just check that something is there.

I agree, and that's what current patch states. @MikeRalphson can you make an example of what you expect here?

[MikeRalphson]

They shall also validate that the customType field is present and populated when the value of securitySchemeType is "custom".

This whole sentence is redundant if customType is REQUIRED when type is custom. It's implicit and we don't repeat ourselves like this elsewhere.

Lots of tools don't validate the input document at all, they just muddle through looking at what they understand. They won't necessarily "throw" on seeing custom. This is true if they are accepting a 3.1.0 document as a backwards compatible superset of the 3.0.0 they actually understand.

When I said securitySchemeType to be a link, I meant a link to the relevant anchor within the document.

[cmheazel]

Our goal is the treat customer Security Schemes the same as any other type of Security Scheme. Therefore: "custom" must be recognized as a valid value for the Security Scheme Type and the customType field is required for custom Security Schemes. I think the changes through line 3182 do this. Line 3185 is informative so it does not have to be written in requirement speak. I'm OK with softening the language in this section.

[ioggstream]

Suggestion: SHALL we move this conversation out of the "outdated" file, eg here https://github.com/OAI/OpenAPI-Specification/pull/1812/files :)

[MikeRalphson]

@darrelmiller as discussed, you volunteered to propose new wording around the extensibility of the http scheme values.

[darrelmiller]

Having reviewed this PR and the current working of the scheme property on Security Requirement Object, it seems sufficiently clear that the http type is an extensibility mechanism for introducing security schemes not currently explicitly mentioned in the OAS.

Field Name	Type	Applies To	Description
scheme	string	http	REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235. The values used SHOULD be registered in the IANA Authentication Scheme registry.