Changes to OAuth2 Authorization declarations

[webron]

Right now this declaration is complex and there are some inconsistencies when declaring OAuth2 Grant flows.
For example, right now Implicit Grant looks like:

"implicit": {
  "loginEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/dialog"
  },
  "tokenName": "access_token"
}

and authorization code looks like:

"authorization_code": {
  "tokenRequestEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/requestToken",
    "clientIdName": "client_id",
     "clientSecretName": "client_secret"
  },
  "tokenEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/token",
    "tokenName": "auth_code"
  }
}

You can see that for the Implicit, the tokenName field as at the base of the object, and in the Authorization Code it's at the Token Endpoint object.

I wrote a post about the possible changes that can be done in the google group, so I'm copying it here directly:

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:

• Authorization Code Grant - uses both.
• Implicit Grant - Only the Authorization Endpoint is used.
• Resource Owner Password Credentials Grant - Only the Token Endpoint is used.
• 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.

Any updates on whether swagger-ui supports the client credentials and password grant types now? If not, any plans to enable these in the near future?

Any pointers to a extension/hack that has enabled these grant types ...

[webron]

At the moment, this is not a swagger-ui issue but rather a specification issue.
Once we allow it, I'm not sure if and when the UI will support it. Community contributions here would help (the original OAuth2 code was a contribution).

[webron]

This has changed as part of Swagger 2.0.

[calfzhou]

Swagger 2.0 doesn't support multiple grant flows in one auth definition. And according to Security Requirement Object doc, if an endpoint have multiple security schemes, all of them are required.

So there is no way to make an endpoint using either auth-code flow or client-credent flow. I need define these two flows using two security schemes, but if an endpoint requires these two schemes, they must be provided both. It's really strange that i have to use two access tokens to access one endpoint.

[webron]

Actually, you can define that. The Security Requirement Object indeed has an AND between the requirements, but when defining the security property, it is an array of Security Requirement Objects and between them, there's an OR. Does that solve your need?

[calfzhou]

whoa! i see, the security property is an array, and there is a logical OR among its items. Each item is an security requirement object, which is a name - scopes hash, and using logical AND among them.

so my problem can be solved by this syntax

"security": [
  {
    "oauth_code": []
  },
  {
    "oauth_app": []
  }
]

is that correct?

Thanks @webron for your clarify. this really helps me a lot.

---

i've one more questions about the scopes. for security scheme with type oauth2, the value is a list of scope names required for the execution, are those scopes using logical AND or OR?

the sample in spec doc:

{
  "petstore_auth": [
    "write:pets",
    "read:pets"
  ]
}

does this mean that this endpoint requires both write:pets and read:pets permission, or any one of them is sufficient?

[webron]

Yup, that's exactly how you'd define it, assuming you don't want to specify any specific scopes for those flows.

As for the scopes, I believe that's an AND between them, I think that's the common practice for OAuth2 flows. Perhaps @fehguy will have more input on it.

[calfzhou]

I myself believe it should be an AND among required scopes. but recently i'm using rails doorkeeper as my oauth2 server, its default behavior is using OR among the scopes, which makes me very confusing.