Which OAuth2 flows does Swagger 1.2 support?

[David Moles]

I'm looking at the 1.2 authorization docs and trying to map it to my application's OAuth2 implementation, and it doesn't quite seem to fit.

We're using the "Client Credentials" flow, in which the client POSTs a key and secret to a token request URL and gets a temporary access token in response, which is then used for the actual API calls. This looks like it ought to correspond to the tokenRequestEndpoint declaration in the authorization_code grant type, but there's only one endpoint, so it's not clear what the tokenEndpoint is for. I assume this is for a different OAuth2 flow than the one we're using?

The app is in flux so we could consider changing our auth flow, if we knew what Swagger supports. If not, we might have to just hack something into the Swagger UI JavaScript.

[tony tam]

Hi, swagger UI supports client flow, take a look at the petstore.swagger.wordnik.com sample. The swagger spec, though, describes the three-legged oauth flow as well

[David Moles]

Hi, Tony. So is the tokenEndpoint optional, and only for the three-legged flow? I'm looking at the petstore sample and I see the tokenRequestEndpoint declaration in http://petstore.swagger.wordnik.com/api/api-docs but I don't see how to actually use it.

[tony tam]

David, that is correct.  The implicit flow is described by the implicit grant type:

grantTypes: 

{

• implicit: 

  {

  • loginEndpoint: 

    {

    • url: "http://petstore.swagger.wordnik.com/oauth/dialog"

    },
  • tokenName: "access_token"

  }

You don't need the authorization_code (three-legged) oauth for this to work.

Take a look at the oauth2 branch on swagger-ui for the supporting code

[David Moles]

Hi Tony,

I don't think that's the same flow I'm talking about. There is no login endpoint, just a client key and secret which are supposed to be baked into the app using the API (or, more likely, baked into a separate server that the app talks to to get its access token).

I've tried the authorization declarations below in my Swagger docs, but I'm still (1) seeing the apiKey input field and (2) not seeing the authentication switches I see in the petstore demo.

////////////////////////////////////////////////////////////
// http://localhost:9090/foo-api/docs
{
    "apiVersion": "0.5",
    "swaggerVersion": "1.2",
    "apis": [
        {
            "path": "/bars",
            "description": "The Bar API"
        }
    ],
    "authorizations": {
        "foo-api": {
            "type": "oauth2",
            "scopes": [
                {
                    "scope": "foo-api"
                }
            ],
            "grantTypes": {
                "authorization_code": {
                    "type": "authorization_code",
                    "tokenRequestEndpoint": {
                        "url": "/v0.5/token",
                        "clientIdName": "client_key",
                        "clientSecretName": "client_secret"
                    }
                }
            }
        }
    }
}

////////////////////////////////////////////////////////////
// http://localhost:9090/foo-api/docs/bars
{
    "apiVersion": "0.5",
    "swaggerVersion": "1.2",
    "resourcePath": "/v0.5/bars",
    "produces": [
        "application/json"
    ],
    "consumes": [
        "application/json"
    ],
    "protocols": [
        "http"
    ],
    "authorizations": [
        {
            "scope": "foo-api"
        }
    ],
    "apis": [
        {
            "path": "/v0.5/bars/",
            "operations": [
                {
                    "method": "GET",
                    "summary": "Get a list of bars",
                    "position": 0,
                    "notes": "",
                    "deprecated": false,
                    "nickname": "Get a list of bars",
                    "parameters": [],
                    "authorizations": [
                        {
                            "scope": "foo-api"
                        }
                    ],
                    "type": "BarResultSet"
                }
            ]
        }
    }
}

I'm using the oauth2 branch of swagger-ui, rev. 3f881c9daf.

Best,

David

[tony tam]

Hi David, is your goal to authenticate a user, or to authenticate the webserver to talk to an app server?  If there's no loginEndpoint, you can't authenticate a user.

If you're describing an anonymous flow, that's different from oauth2 implicit and authorization code flows.  Perhaps I just need to hear more of your use case?

ps. we're documenting this whole portion of swagger right now, perhaps you can give some feedback on the docs, which we should have tomorrow?

[David Moles]

Hi, Tony --

The goal is to authenticate a web server (or an app) to talk to an API server, system-to-system. There's no users at this point. The flow we're looking at is section 4.4 of the OAuth2 RFC, also described in this blog post. The client sends key+secret with basic-auth to the server, gets a token, and uses that token with bearer-auth to make API requests till the token expires.

--D.

[tony tam]

Got it.  This blog post is describing a modified version of the client credentials (password) flow and unfortunately we have not implemented that for swagger.  We've only implemented implicit and authorization code flows thus far, although I'd like to have the password flow.

Sorry for the confusion.  It's fairly easy to add this but I don't see it happening for several days.  If you want to look at the source for the swagger-ui, you can probably do it easily.  The technique for adding headers, etc. will be the same.

[David Moles]

Okay. I've modified my swagger docs to generate my best guess at what a client_credentials flow ought to look like, and I've got the swagger-ui source (oauth2 branch) checked out and building. Can you give me any hints as to where to start looking for how the existing OAuth2 integrations work?

Also, re: documentation: the authorization example in the docs has

"authorizations" : {
    "local-oauth": {
      "type": "oauth2",

but in the petstore example it's

"authorizations": {
    "oauth2": {
      "type": "oauth2"

When I grep for oauth2 in the source, I find this

    @model.oauth = null
    if @model.authorizations
      for k, v of @model.authorizations
        if k == "oauth2"
          if @model.oauth == null
            @model.oauth = {}
          if @model.oauth.scopes is undefined
            @model.oauth.scopes = []
          for o in v
            @model.oauth.scopes.push o

which suggests that it's expecting "oauth2" to be the name as well as the type. But since I have only the vaguest notion what the source is doing it's hard to tell. Can authorizations be named freely, as the doc implies, or not?

If not, that might explain why I wasn't seeing any authorization switches. You might consider only using the actual petstore sample code in your documentation code samples, since that's known to work.

[tony tam]

Hi David, you are right, the current code requires the key to be "oauth2".  I will update that.

The way the implicit flow works is that it will render the auth button if it sees "oauth2" as a required authorization.  clicking it will trigger the flow, where the end result is a javascript call here:

https://github.com/wordnik/swagger-ui/blob/oauth2/dist/lib/swagger-oauth.js#L137

Which does some fancy stuff to change the state of the auth buttons.  It ultimately adds the header here:

https://github.com/wordnik/swagger-ui/blob/oauth2/dist/lib/swagger-oauth.js#L189

Which enables the user to call the API.

All you really need is to get the header set in the client per line 189.

[Ron]

Okay, as Tony mentioned, I'm currently working on the Authorization documentation in the spec.

I've actually read the blog posts mentioned by David before reading this thread, only I concentrated on the first two grant flows described there.

Looking at the the spec - http://tools.ietf.org/html/rfc6749 - and based on those blog posts, it seems that the whole definition can be simplified.

There are two type of endpoints involved in the OAuth2 process - the Authorization Endpoint and the Token Endpoint (http://tools.ietf.org/html/rfc6749#section-3).

These two endpoints are used in the 4 different grant flows (http://tools.ietf.org/html/rfc6749#section-4), but they're not always used.

So we have this:

1. Authorization Code Grant - uses both.
2. Implicit Grant - Only the Authorization Endpoint is used.
3. Resource Owner Password Credentials Grant - Only the Token Endpoint is used.
4. Client Credentials Grant - Only the Token Endpoint is used.
   

As far as I can tell, you can basically support all grant flows with those two endpoints. The difference between them will be with the parameters sent to them, and those are completely controlled by the client performing the authorization.

Currently, the swagger specification officially supports only the first two grant flows, but as you can see, we can easily modify it to support all four.

I would suggest it looks like:

"authorizations" : {
    "auth_name" : {
        "type" : "oauth2",
        "scopes" : ["scope1", "scope2", "..."],
        "authorizationEndpoint" : "https://....",
        "tokenEndpoint" : "https://....",
        "grantFlows" : ["Authorization Code", "Implicit", "Resource Owner Password Credentials", "Client Credentials"]
    }
}

If the server uses different authorization and token endpoints for different grant flows, then they could just create a different "auth_name" per set.

It's a good idea to keep the "scopes" there as this is metadata the developers may need to develop the app. In fact, we may want to expand on each scope giving an additional description to them so that the developer knows which scope means what.

One important difference between that and the current implementation is that it does not include the "tokenName", "clientIdName" and "clientSecretName" parameters. As far as I understand, those are meant to allow some flexibility in deciding what these parameters can be called. However, if I've read the oauth2 spec correctly, they are always "access_token", "client_id" and "client_secret" (respectively). In other words, the oauth2 spec doesn't allow flexibility in the naming convention and as such, we don't need to allow that in the swagger spec as well.

Please share your thoughts on the matter.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[David Moles]

That all sounds great to me. Presumably of you're doing Implicit you can leave off the Token endpoint and if you're doing Resource Owner or Client Credentials you can leave off the Authorization endpoint.

FWIW, since our service only needs Client Credentials, uses it for everything, and is supposed to be code-complete in about a week, for the time being I'm just hacking something in that will replace the global ApiKeyAuthorization (& its form field) with a ClientCredentialsAuthorization that can synchronously get the token. But we'll definitely be looking forward to the official OAuth2 support when we add more API calls and our authentication picture gets more complicated.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/WdMcNhTET_s/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.

--
David Moles
http://www.chrononaut.org/

[Ron]

By the way, I just noticed that scopes do have descriptions on them. Perhaps another thing they can have is an optional list of supported grant types (the default being all the ones that are listed). I'm not sure how valid/relevant this use case is.

[Gautam Priya]

Hi Tony - Any updates on support within swagger for the client credentials and password grant_types.

Thanks

[Gautam Priya]

Hi David, Ron,

I am in a similar situation currently and need to implement support for password and client_credentials grant types in swagger-ui. Judging by your posts on this thread, I believe that you were in a similar boat some time earlier this year. Were you able to make swagger-ui work with the client_credentials grant type? If yes, I would appreciate if you would kindly share your learnings from your experience? Also, are you aware if the swagger team at Reverb has(/plans to) incorporated changes to make this happen? 

Thanks

[David Moles]

Hi Gautam,

We ended up having to make some modifications to the swagger-ui source code to hack in client credentials support. Unfortunately I'm not on that project any more and don't currently have access to the source code, but I think it was fairly straightforward once we reverse engineered the existing ApiKeyAuthorization code.

Best,

David

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/WdMcNhTET_s/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Ron]

Guatam,

Just so we're on the same page, can you share you're swagger authorization declaration?

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Pete Clark]

I realize this is an old topic, but were client_credentials ever implemented in swagger-ui?  I have searched the source code and thus far haven't found any evidence of it. 

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
David Moles
http://www.chrononaut.org/

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron Ratovsky]

client credential flow is what we refer to as application flow in the spec, and no, it's not implemented in the UI yet.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
David Moles
http://www.chrononaut.org/

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------