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 [email protected] 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 https://github.com/OAI/OpenAPI-Specification/issues/61#issuecomment-296410810, 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.

[starfishmod]

@webron is it just the 3.0.md file I should make a PR to? or is there other files I should consider?

[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?