Deprecate security schemes

[miqui]

Although the OpenAPI specification supports multiple security schemas and associated schemes

• HTTP
• apiKey
• oauth2
• openIdConnect

Of this set http (for basic is most likely the most insecure. There is plenty of documentation concerning API security that suggests that a basic scheme is a bad idea. However, to facilitate the transition of an API that is using HTTP basic to a more secure scheme, I propose to add the deprecated attribute to the Security Scheme Object of the specification. Note, that there is some mention of deprecation in the 3.1 specification, but it seems to imply that deprecation is the responsibility of the scheme type (Oauth 2, implicit flow) owner.

Example:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      deprecated: true

The API's behavior could be reflected (i.e. signal to consumers) by using something similar to Deprecation HTTP header field draft for the deprecated scheme.
Note:

• deprecation could be reflected in the swagger-ui if http basic is used and flagged as deprecated.

General references

• IANA Authentication Scheme registry

[handrews]

@miqui I'm moving this over to a discussion in the "ideas" category because that's where folks are looking for ideas to review right now. We're only using issues for a few things in this repo that are short-term actionable.

[miqui]

thanks @handrews

[lornajane]

There are valid use cases for HTTP basic auth and OpenAPI is here to enable interoperable descriptions, I don't think the standard should judge if someone should be doing that or not, which it sounds like what is being suggested here

[rafalkrupinski]

I think the proposal is about adding deprecated property to the security scheme object, so that the document author can discourage use of that particular scheme, while still allowing it.

[miqui]

@rafalkrupinski - That is correct. Similar to deprecating a resource use case already established in the specification. We should give API providers the same ability to discourage the use of the particular scheme while providing a migration pathway for the provider and the consumer.

[rafalkrupinski]

I think the title is ambiguous at best.

[SensibleWood]

For me the key thing is what an API consumer and their applications can actually do with this information. Flagging something as deprecated and leaving it at that is not massively informative unless its accompanied by a bunch of other information describing the reasons for deprecation, when the Security Requirement will be sunsetted, etc. etc. Just because something like Basic Auth is used less commonly doesn't mean its not used with good reason, and by design.

We should probably look into any other such properties to support this approach and decide on whether it provides valuable information for the API consumer - and therefore should be in the specification - or whether that information bloats the specification and belongs elsewhere.

[miqui]

hi @SensibleWood

Flagging something as deprecated and leaving it at that is not massively informative unless its accompanied by a bunch of other information describing the reasons for deprecation, when the Security Requirement will be sunsetted, etc. etc.

Indeed you are right on this point. But, the same can be said about the current Operation Object attribute deprecated. The language in the spec is:

"Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false."

Thats it. Nothing more and/or at least prescriptive about what else the API provider should do to provide additional context to make this more actionable/informative. Today, the swagger-ui just grays out the resource with the hope that this is informative enough. (note: I believe many developers/teams are not used to sunsetting or deprecating at all - but hey, we have to start somewhere)

To make matters worse we cannot guarantee what tool providers do with this information. The spec leaves it up to their implementation. But, at least what I have seen/experienced on many tools both open-source and commercial is that there is a similar visual feedback and nothing more. At the end of the day, it is the responsibility of the API owner to take full ownership of deprecation and follow whatever best (good?) practices to help their consumer transition to a more secure API. The spec does not go into detail here and it should not anyway.

Just because something like Basic Auth is used less commonly doesn't mean its not used with good reason, and by design.

Agreed 100%. Which is why the attribute MUST BE optional. An API provider owns their design choices. Want to keep using HTTP? Go for it, I am sure they have their reasons.

We should probably look into any other such properties to support this approach and decide on whether it provides valuable information for the API consumer - and therefore should be in the specification - or whether that information bloats the specification and belongs elsewhere.

Awesome. To decide what others consider valuable is a tough exercise. I am all for it. Perhaps out of this exercise, the same good ideas can be retroactively applied to the Operation Object.

Thanks a lot for your feedback - awesome!

[rafalkrupinski]

For me the key thing is what an API consumer and there applications can actually do with this information.

Yeah, recommendations and best practices would be more than welcome.

Flagging something as deprecated and leaving it at that is not massively informative unless its accompanied by a bunch of other information describing the reasons for deprecation, when the Security Requirement will be sunsetted, etc. etc.

IMO the role of deprecation flag is to bring attention. Sure it's nice when it comes with a message, but many objects already have description. Perhaps it could be mentioned somewhere that authors should put details there, and tools should point to to it when deprecated is encountered.

[miqui]

IMO the role of deprecation flag is to bring attention. Sure it's nice when it comes with a message, but many objects already have description. Perhaps it could be mentioned somewhere that authors should put details there, and tools should point to to it when deprecated is encountered.

exactly! @rafalkrupinski . Just the other day I was doing some c++ coding with CLion IDE from Intellij. I tried including ```#include "strings.h" and the IDE gave me a deprecation warning with a SUGGESTION on what is the preferred include.

The spec "has an education" component to it to guide folks in the API space. No sticks, just guidance. At the end of the day you own your own design choices.