Add support for an OAuth 1.0 authorization scheme

[cfournie]

Currently, the Swagger 1.2 specification supports three authorization schemes: basic authentication, API key and OAuth2. One popular scheme that is missing is OAuth 1.0; can it be added to the next specification version?

[abdennebi]

Please add OAuth 1.0 support !

[webron]

I believe it would help if you could provide a sample of how you expect to OAuth 1.0 support to look like.
We don't necessarily have the experience with it to properly implement support for it.

[seppkurt]

see http://oauth.net/core/1.0a/ any plans on this. swagger is cool but we cannot used it in full features!

[webron]

Parent: #585.

[starfishmod]

+1 for this
I have been writing Swagger specs for the following all using oauth1

• Xero
• Wordpress API v2
• twitter
  plus a few more on the way

can we just have something like this:

"oauth": {
            "type": "oauth1",
            "flow": "implicit", /*Not sure if this is needed??? or what should be here*/
            "authorizationUrl": "https://api.twitter.com/oauth/authenticate",
        "requestUrl": "https://api.twitter.com/oauth/request_token",
            "tokenUrl": "https://api.twitter.com/oauth/access_token",
            "scopes": {
                "basic": "to read any and all data related to twitter\n"
            }
        }

This have covered all the use cases so far I have dealt with. Happy for it to be improved and modded but this needs improving implementing.

[ChriWiChris]

Hi,
I am also in the situation in which I'd like to write the specification including oauth1.
@starfishmod 's idea would be nice.
Regards

[weislakb]

Is there any new status on this? I think the OpenAPI spec would be much more flexible if it had support for OAuth1. Thanks!

[ukumava]

Hi , Is OAuth1 now supported in Swagger? If it is where can I find sample implementation.

[RobDolinMS]

@cfournie Is this sufficiently resolved in the latest OAI v3 spec?

[cfournie]

Not AFAICT

[webron]

@RobDolinMS Support for OAuth1 was not added to v3. IIRC, we've discussed it and decided to not support it.

[starfishmod]

Can I ask why? - since OpenAPI is about describing API specs - what harm is there in supporting a widely used auth mechanism in a spec? I'm not advocating for using Oauth1 - I'm only advocating for being able to describe existing API systems that currently use them. In my example I have written a Swagger generator for the WP API v2 handling. The mechanism for authentication currently recommended is the WP Oauth 1a plugin. There is no appropriate Oauth2 auth mechanism and the other header mechanism is not common and has no third party libraries to help people log in. I have come across other Oauth1a only restful API's as well that need describing as well.

…

On 23 April 2017 at 10:31, Ron ***@***.***> wrote: @RobDolinMS <https://github.com/RobDolinMS> Support for OAuth1 was not added to v3. IIRC, we've discussed it and decided to not support it. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#61 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAs6kzgu0qPpuKaa2qk0ahQa3dsjNLXpks5rypvjgaJpZM4B9u52> .

-- Regards Andrew

[webron]

I don't believe it is that widely used anymore. I doubt anyone writing a new API would choose OAuth1 over OAuth2. We also don't support describing other APIs due to their structure and so on.

I'm no expert on OAuth1. From the little I know, it would be more challenging to describe (if we want to cover all use cases). We're at the point of a feature freeze for 3.0.0 so if it didn't make it until now, it's unlikely we'll have time to explore it further and try to pull it in.

[starfishmod]

I don't believe it is that widely used anymore. I doubt anyone writing a new API would choose OAuth1 over OAuth2.

So Twitter and wordpress isn't widely used? Both structures are Restful and can be described via OpenAPI 2 except for the Oauth1a requirement. I can find plenty of other popular API's e.g. yelp that is still on Oauth1a - may I suggest you research more before being dismissive of legacy apps that could have a OpenAPI spec easily added to them?

I'm no expert on OAuth1. From the little I know, it would be more challenging to describe (if we want to cover all use cases). We're at the point of a feature freeze for 3.0.0 so if it didn't make it until now, it's unlikely we'll have time to explore it further and try to pull it in.

Ok so when do you expect this to go into the spec? v4? I ask because this request has been around for sometime it is a popular topic and comes up time and time again. When do you (or the Open API team) expect to find an expert in Oauth1.0a so you can add to the spec if you are not knowledgeable enough? If an expert does put their hand up will it be added to the spec? Or will it be dismissed as the impression I get from your words is that OpenAPI does not seem to cater to legacy API's unless they also want to change their auth mechanism?

[earth2marsh]

I continue to hear providers considering OAuth 1.0a for their APIs, sometimes because they have other APIs that use it, other times because they like the cryptographic signing. It seems to me that the argument for adding support for being able to describe cookie-based auth had a similar rationale.

[webron]

@starfishmod The attitude is really uncalled for, but I'll give you the benefit of the doubt that it is coming out of frustration and not for other reasons. I won't go into the arguments you brought up and go back and forth on this, because it won't move us forward.

To me, @earth2marsh's comment added more value. I wasn't really in favor of adding cookie support, but I don't see this at the same level. The reasons that support wasn't added so far are - 1. we don't know it well enough, 2. even if it can be described, we want to make sure that it can be described in a way that tools can use. It might be obvious, but I'd rather not assume.

We've put a lot of work into 3.0, but we also have limited time and resources. Some things just did not make the cut. If we thought this had no room in the spec, I would have closed the ticket rather than just add the comment that we've decided to not support it in 3.0.

The changes to the security definitions structure should hopefully allow us to add support for more structs in 3.1 as a non-breaking change. Whether it we will or won't support it is beyond my abilities to see the future.

I appreciate the suggested example you gave above, however, I don't think it covers the full options of OAuth1.0a. We might not even need to cover the full options, I simply don't know. Out of the 10 participants in this thread, there wasn't really a lot of feedback on your suggestion, no follow-up discussion (which I read as little community interest, sorry).

3.0.0 is feature complete. It's unlikely that within the time we have before the official release that we'll be able to research the topic, come up with a solution, verify and put it in the spec. @earth2marsh - if you know the topic more and think the risk is low, please add a comment here and maybe the community will jump on it and help us make it happen.

[starfishmod]

@webron sorry, I don't understand the "attitude" you are referring too. Sure I asked you hard questions based on your own words. You also seem to speak from authority about this project; you seem to make decisions, and it came across that because you see no value, as you personally wouldn't write a new API using Oauth1a, and in your words "it was discussed" (where? when?) and was therefore not going to be supported. All this you did without explanation as to the reasons, leaving those that need it in the dark. So these were fair comments to make.

I appreciate the longer and more thoughtful reply and I can better understand the limited resources issue and why it wasn't looked at for now.

So lets break down the concerns about adding Oauth1a, and please correct me if I'm wrong:

It's not understood well enough in the OpenAPI team and they don't know which parts should or should not be supported of the Oauth spec.
So if someone who is more knowledgeable can verify what is needed is that ok? There are several comments above stating the spec (granted for v2) example given covers all cases being currently used. What exactly is missing?
I get that you don't personally know and don't have time to look. But you keep saying it's not complete but not why? So we are left with "something is missing but we don't know what, nor can a problem be described where the missing piece has been hit, but we won't go forward because... just because...?".

There is a concern about the tooling and if that will work?
I'm confused I thought OpenAPI was tooling agnostic? Which tooling is of concern? I can only speak from my anecdotal experience, and so far have hit no road blocks in any tools I use that can handle an Oauth1a login in the same way as using Oauth2, however I would like to know more about this. Do you have specific tools that must be supported?

A concern that Oauth1a is deprecated or of low use in the real world
I agree that @earth2marsh makes a good point regarding this. Also as expressed earlier a lot of existing/legacy API's which are restful cannot be described currently.

However I would also argue that since Oauth1a is in limited use (compared to Oauth2) then perhaps a minimal or basic spec description is all that is required - instead of trying to cover 100% of all use cases, cover 80% and then revise from the feedback of people who use Oauth1a.

The only changes I would make to my solution above after using it for a while is the removal of flow (unused) and changing type to oauth1a (from oauth1)
Note I'm not asking you to take my suggestion (I honestly don't care), I'm just looking for an official solution that allows the some initial description of Oauth1a so we can move forward.

[starfishmod]

To further comment about perceived issues with Oauth1 - again I'm looking for corrections if I'm wrong.

Oauth1a is more complex than Oauth2
I would contest this - all examples I have seen is that Oauth2 is a more complex protocol with more back and forth and has more options required than Oauth1a e.g flow. However since libraries tend to hide complexities of both Oauths it is likely not a concern?

[earth2marsh]

I wouldn't claim to know the topic particularly well. The most common form was 3-legged (Twitter-style) OAuth 1.0a. In the past, a 2-legged variant would sometimes crop up, but I can't remember an API I've used in two years that didn't use the client credentials grant of OAuth 2.0 (plus IIRC, 2-legged wasn't covered in the 1.0a spec).

@starfishmod For tooling like code generators or interactive documentation, end users will expect that providing a spec with OAuth 1.0a is supported—that's the tooling burden to consider. Writing, testing, maintaining that code is non-trivial work. Yes, it seems a shame that not supporting a reasonably common auth flavor might prevent someone from describing a service like Twitter (plus, specification extensions don't seem to help here).

Without more comments from the community, it's hard to justify slowing down the RC process vs this being reconsidered as a 3.1 candidate story. Who else is blocked on this?

[raymondfeng]

See https://github.com/jaredhanson/passport-oauth1 for a list of configurable properties needed to interact with an oAuth 1.0 provider. For example:

{
    requestTokenURL: 'https://www.example.com/oauth/request_token',
    accessTokenURL: 'https://www.example.com/oauth/access_token',
    userAuthorizationURL: 'https://www.example.com/oauth/authorize',
    consumerKey: EXAMPLE_CONSUMER_KEY,
    consumerSecret: EXAMPLE_CONSUMER_SECRET,
    callbackURL: "http://127.0.0.1:3000/auth/example/callback",
    signatureMethod: "RSA-SHA1"
  }

[starfishmod]

@raymondfeng awesome good spot on signature method, and interestingly enough AFAIK the Oauth 2 spec doesn't have a place for the consumer keys and the callback url. So maybe just the requestTokenURL, accessTokenURL, userAuthorizationURL and signatureMethod?

So maybe it should look like this in 3.1?

{
  "type": "oauth1a",
   "authorizationUrl": "http://example.com/api/oauth/dialog",
   "tokenUrl": "http://example.com/api/oauth/token",   
   "requestUrl": "http://example.com/api/oauth/request",
   "signatureMethod": "RSA-SHA1"
}

With the signature method being HMAC-SHA1 by default and however the it must be one of "HMAC-SHA1", "RSA-SHA1", and "PLAINTEXT"?
The URL's must all be required?

[MikeRalphson]

RAML 1.0 defines the properties necessary for oAuth1 authentication as follows

[starfishmod]

@MikeRalphson Ok that makes sense the signature method is an array of available signatures so revising above :

 {
  "type": "oauth1a",
   "authorizationUrl": "http://example.com/api/oauth/dialog",
   "tokenUrl": "http://example.com/api/oauth/token",   
   "requestUrl": "http://example.com/api/oauth/request",
   "signatureMethod": ["RSA-SHA1"]
}

So if this sounds ok I can make a PR over the next few days?

[webron]

@starfishmod PRs are definitely welcome. To set expectations, we cannot guarantee the PR will be fully reviewed and accepted before the 3.0 release (we are at a feature freeze), but we'll do our best.

[webron]

Just that file.

[RobDolinMS]

PR #1080 addresses this.

[darrelmiller]

Re-opened for future consideration post v3.0.0

[starfishmod]

FYI have posted to #1080 examples of the security scheme proposed and how it would work with a variety of providers and providers it may have trouble with. I'm asking for feedback so it can be reviewed further.

[starfishmod]

Any further update on when this may be reviewed to go into the next release?

[darrelmiller]

I have asked some OAI members with a deeper understanding of security to review this.

[starfishmod]

@darrelmiller great - what is the expected eta on that review completion?

[jamalkhattab]

Are there any updates?

[starfishmod]

I am wondering where this is currently at? The last official(?) response was 5 months ago. I'm still requiring this in the OpenApi spec for my use cases - is it possible to add to 3.0.2?

[webron]

We had a lot of discussions on OAuth 1.0 and came to the same initial conclusion - the OAuth 1.0 implementations are too varied to be able to provide a way to describe it and have it useful. As such, we've decided to put it on hold.

If it would be added, it would need to be in the next minor version and not patch version, following semver.

[starfishmod]

@webron thanks for the update.
However could you please clarify what you mean by varied? I'm unclear as the proposed additions covered the variations amongst the many existing Oauth1 implementations. You can see this in #1080 where I provided many examples of how this would work.

Ok so what needs to be done to get it into the next minor version? How can this be achieved?
What is the next minor version release date?

[webron]

@starfishmod it's pretty much what @darrelmiller described in #1080 (comment) followed by the discussion you two had over there.

At the moment, we haven't had additional discussions for supporting OAuth1 in the next minor version. We don't have an ETA for its release either.

@MikeRalphson - this may fall under your security-features umbrella.

[starfishmod]

@webron yes the comment in question in #1080 was responded to. Which I covered the concerns raised and provided the information as requested on June 11th last year.
I don't know what else you wish for me to provide to get this added? I have given OAI Team as much information, PR's and quite a few individual end point examples as requested, and I still don't know what is missing to get this in?

Oauth1 is not perfect and it seems the rejections are based on Oauth1's design flaws (or because some end points have implemented it poorly), not because the PR is wrong? Unfortunately I can't fix Oauth1 flaws I can only describe the working examples that are provided by end points.

Please provide clear directions on what I can do to get this added? If there is nothing I can do then please say so.

[webron]

No, you can't fix OAuth1's flaws, but if adding 'support' to it will only give tool providers and users as a result more headache than benefit, then there's really no more value providing that kind of support than having users describe it using extensions.

We had several discussions about it in the meetings - and the last one had a representative (can't recall who) who pretty much guided us to the same conclusion - introducing it into the spec will cause more problems than providing benefits.

I can't provide you clear directions on what you can do to get this added. You're welcome to join one of our calls and present your points, though it's better to schedule it in advance. We're considering a few additions/changes to the spec right now, personally, it's not on my priority list but I definitely can't speak for the other @OAI/tsc members.

[niklasskoldmark]

Hi, are there any news on adding OAuth 1.0 to the Security Scheme types?
I'm not suggesting that it is a good choice when designing a new API, but there are still many widely used services that utilize OAuth 1.0 as their only method of authorization.
One example that I'm currently working with is Apple's MDM API.

From what I understand OAI is meant to be useful for describing, consuming and visualizing existing API's as well as for creating new ones.

Thanks for a great tool BTW ;)

[jeremyjs]

We were looking to Open API to serve as a universal and open standard, however without first-class support for OAuth 1.0, it does not currently appear to be fully universal. We would really prefer Open API to become universal, rather than have to invent a new standard to compete or become a superset. For that reason we really advocate for OAuth 1.0 support regardless of its legacy status or even difficulties that may occur as a result. Otherwise how is any sufficiently complex system supposed to handle authorization and request signing in a standardized way? So rather than eventually forking it, we would prefer to advocate for it to be implemented into the existing Open API Specification. But in the meantime we will be implementing a patch in our system to label endpoints as OAuth 1.0.

[handrews]

@jeremyjs @niklasskoldmark I've opened an OAS 4 (Moonwalk) discussion on making it easier to support alternative authentication processes. I think it is best to close this issue in favor of that discussion.

While it might be possible to add this to 3.2 under SemVer, it's clear from the discussion above that there is little appetite for it. 3.2 is likely to be small and focused on easing the path to Moonwalk.

I'll leave this open for a bit in case someone wants to argue for 3.2 inclusion, simply because we haven't yet defined inclusion criteria for that release.