thoughts about auth strategies

[calfzhou]

Current strategies (default, protected, and swagger) are not very handy to use. I guess that swagger could be an additional configuration, injecting swagger specific syntax. And for the protected, maybe there could be a class method such as oauth_all (see the guard! and guard_all! in this demo app) which could protect the entire class.

[antek-drzewiecki]

Good thinking. This would be a great improvement. This is actually what the protected strategy is doing.
The reason why strategies were introduced is because it was quite difficult to protect an entire class and inject swagger syntax on class loading. I'll be happy to accept PR's that lead into simplifying protection of the API.

[sunnyrjuneja]

I'm in agreeance here. I'm happy to send a PR that moves swagger as a configuration option but I'm having a hard time understanding what the difference is between the swagger and default strategy. Do you mind explaining how the swagger strategy works @antek-drzewiecki?

[sunnyrjuneja]

Also, @calfzhou, right now, the protected strategy automatically protects all endpoints (similar to guard_all! is doing now). Protecting an entire class is interesting idea. Maybe we can add that as a method on the default strategy.

[calfzhou]

@whatasunnyday , agree with you.

The only problem for class level protection (guard_all!) is as @antek-drzewiecki mentioned, that you still need add an oauth2 SCOPES to each endpoint to inject swagger doc.

[sunnyrjuneja]

@antek-drzewiecki sorry to ping you again but what is the difference between swagger strategy and default?

[antek-drzewiecki]

@whatasunnyday no problem. The difference is that the swagger strategy inject an authentication hash in the endpoint description that is compliant with grape-swagger. Grape-swagger will generate valid Swagger-UI json with the authentication options. Finally Swagger UI can parse the output and set authentication toggles. WineBouncer then uses this authentication hash to authenticate the scopes. Injecting the authentication hashes in the grape endpoints is the main purpose of the strategy. Currently the injection of the authentication hashes and and the authentication process are intertwined, but this could become separate methods.

To summarize, the swagger strategy is default strategy + authentication hash injection.

I hope you understand the goal of the swagger strategy now.

Here are some link to the spec link and the actual endpoint spec. Since the spec is hard to read. Ill give you an example how the hash should look like:

authorizations: {
  oauth2: [
    { 
     scope: "required_scope"
    }
  ]
}

Here are some more resources.
Swagger UI example: https://grape-doorkeeper.herokuapp.com/documentation
Raw output of the example as generated by swagger: https://grape-doorkeeper.herokuapp.com/api/v1/swagger_doc/me
Sample app on github: https://github.com/sethherr/grape-doorkeeper

[penso]

@antek-drzewiecki Am I wrong thinking the documentation link should show the oauth calls in swagger? That's the reason I wanna use wine_bouncer and using the :swagger auth strategies I see none.

[antek-drzewiecki]

You are not wrong @penso. It should, but it relies on the grape-swagger gem to get the the authentication buttons in swagger. Adding the grape-swagger gem should fix it for you.

[penso]

@antek-drzewiecki I actually have gem 'grape-swagger' but I still don't see it. I'll dig further then.

[antek-drzewiecki]

@penso is your endpoint also tagged with scopes like: oauth2 'public', 'write' ?
Then the endpoint json should really include the authorizations tag.

[penso]

@antek-drzewiecki Sorry I meant I don't see any documentation about the /oauth/token endpoints to tell my users which endpoint they should be using for the oauth part. I wasn't talking about the authorization tag (which being honest, I haven't looked at yet). But I do see something on the right side of the API documentation listing my scope so I guess that part is working.

[antek-drzewiecki]

Merry Christmas! swagger-ui doesn't give much information regarding the OAuth end points to be honest. You will be probably ending writing your own documentation for that part. As far as I know swagger ui only documents your endpoints.

The scope part is indeed working then!

If I'm delayed while writing back I am on a small holiday ;)

Op 25 dec. 2015 om 13:19 heeft Fabien Penso [email protected] het volgende geschreven:

@antek-drzewiecki Sorry I meant I don't see any documentation about the /oauth/token endpoints to tell my users which endpoint they should be using for the oauth part. I wasn't talking about the authorization tag (which being honest, I haven't looked at yet). But I do see something on the right side of the API documentation listing my scope so I guess that part is working.

—
Reply to this email directly or view it on GitHub.

[penso]

@antek-drzewiecki Don't you think wine_bouncer should generate the endpoint documentation so they appear in swagger? The only way for me to include those right now would probably to fake methods in Grape, as detailed in http://stackoverflow.com/questions/27661166/how-i-can-add-an-external-api-documentation-into-swagger-using-grape-swagger

[antek-drzewiecki]

Hi @penso , its a good idea though. Do you mean it should generate an separate swagger (json) documentation for the authentication endpoints?

Otherwise I still see some issues. Having a look at the OAuth2 spec the spec talks about an resource and an authentication server. The resource and authentication server can have different base urls. The resource can be api.website.xx and the authentication can be auth.website.xx. This will be really confusing when they are under one documentation scheme.

[penso]

I think on many projects you actually have the same base url, so you probably would like to be able to do either (two swagger files, or one) depending on your usage. Having all within the same swagger is nice when you have the same base url.

[echan00]

@penso did you find a solution? I'm also hoping for the oauth endpoints to be in swagger documentation.

If you've manually described them in your project, it would be great if you could share.