diff --git a/CHANGELOG.md b/CHANGELOG.md index 18956731..ac67d9b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ #### Features +* [#510](https://github.com/ruby-grape/grape-swagger/pull/510): Use 'token_owner' instead of 'oauth_token' on Swagger UI endpoint authorization. - [@texpert](https://github.com/texpert). * Your contribution here. #### Fixes diff --git a/README.md b/README.md index fe5946d4..f2a743d3 100644 --- a/README.md +++ b/README.md @@ -196,7 +196,7 @@ end * [markdown](#markdown) * [endpoint_auth_wrapper](#endpoint_auth_wrapper) * [swagger_endpoint_guard](#swagger_endpoint_guard) -* [oauth_token](#oauth_token) +* [token_owner](#token_owner) * [security_definitions](#security_definitions) * [models](#models) * [hide_documentation_path](#hide_documentation_path) @@ -296,13 +296,13 @@ add_swagger_documentation \ swagger_endpoint_guard: 'oauth2 false' ``` - -#### oauth_token: -Specify the method to get the oauth_token, provided by the middleware. + +#### token_owner: +Specify the token_owner method, provided by the middleware, which is typically named 'resource_owner'. ```ruby add_swagger_documentation \ - oauth_token: 'doorkeeper_access_token' + token_owner: 'resource_owner' ``` @@ -836,9 +836,10 @@ end The Swagger UI on Grape could be secured from unauthorized access using any middleware, which provides certain methods: -- a *before* method to be run in the Grape controller for authorization purpose; - some guard method, which could receive as argument a string or an array of authorization scopes; -- a method which processes and returns the access token received in the HTTP request headers (usually in the 'HTTP_AUTHORIZATION' header). +- a *before* method to be run in the Grape controller for authorization purpose; +- a set of methods which will process the access token received in the HTTP request headers (usually in the +'HTTP_AUTHORIZATION' header) and try to return the owner of the token. Below are some examples of securing the Swagger UI on Grape installed along with Ruby on Rails: @@ -856,14 +857,14 @@ This is how to configure the grape_swagger documentation: hide_format: true, endpoint_auth_wrapper: WineBouncer::OAuth2, # This is the middleware for securing the Swagger UI swagger_endpoint_guard: 'oauth2 false', # this is the guard method and scope - oauth_token: 'doorkeeper_access_token' # This is the method returning the access_token + token_owner: 'resource_owner' # This is the method returning the owner of the token ``` The guard method should inject the Security Requirement Object into the endpoint's route settings (see Grape::DSL::Settings.route_setting method). -The 'oauth2 false' added to swagger_documentation is making the main Swagger endpoint protected with OAuth, i.e. it -is retreiving the access_token from the HTTP request, but the 'false' scope is for skipping authorization and showing - the UI for everyone. If the scope would be set to something else, like 'oauth2 admin', for example, than the UI +The 'oauth2 false' added to swagger_documentation is making the main Swagger endpoint protected with OAuth, i.e. the +access_token is being retreiving from the HTTP request, but the 'false' scope is for skipping authorization and +showing the UI for everyone. If the scope would be set to something else, like 'oauth2 admin', for example, than the UI wouldn't be displayed at all to unauthorized users. Further on, the guard could be used, where necessary, for endpoint access protection. Put it prior to the endpoint's method: @@ -886,7 +887,7 @@ And, finally, if you want to not only restrict the access, but to completely hid users, you could pass a lambda to the :hidden key of a endpoint's description: ```ruby - not_admins = lambda { |token=nil| token.nil? || !User.find(token.resource_owner_id).admin? } + not_admins = lambda { |token_owner = nil| token_owner.nil? || !token_owner.admin? } resource :users do desc 'Create user', hidden: not_admins @@ -897,7 +898,7 @@ users, you could pass a lambda to the :hidden key of a endpoint's description: end ``` -The lambda is checking whether the user is authenticated (if not, the token is nil by default), and has the admin +The lambda is checking whether the user is authenticated (if not, the token_owner is nil by default), and has the admin role - only admins can see this endpoint. diff --git a/lib/grape-swagger/doc_methods.rb b/lib/grape-swagger/doc_methods.rb index 5713d55c..887656ac 100644 --- a/lib/grape-swagger/doc_methods.rb +++ b/lib/grape-swagger/doc_methods.rb @@ -97,7 +97,7 @@ def defaults specific_api_documentation: { desc: 'Swagger compatible API description for specific API' }, endpoint_auth_wrapper: nil, swagger_endpoint_guard: nil, - oauth_token: nil + token_owner: nil } end diff --git a/lib/grape-swagger/endpoint.rb b/lib/grape-swagger/endpoint.rb index 2fd2d748..4e667501 100644 --- a/lib/grape-swagger/endpoint.rb +++ b/lib/grape-swagger/endpoint.rb @@ -304,7 +304,7 @@ def model_name(name) def hidden?(route, options) route_hidden = route.options[:hidden] return route_hidden unless route_hidden.is_a?(Proc) - options[:oauth_token] ? route_hidden.call(send(options[:oauth_token].to_sym)) : route_hidden.call + options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call end def public_parameter?(param) diff --git a/spec/swagger_v2/guarded_endpoint_spec.rb b/spec/swagger_v2/guarded_endpoint_spec.rb index d9dd7a79..e4966b9c 100644 --- a/spec/swagger_v2/guarded_endpoint_spec.rb +++ b/spec/swagger_v2/guarded_endpoint_spec.rb @@ -21,6 +21,10 @@ def access_token def access_token=(token) @_access_token = token end + + def resource_owner + @resource_owner = true if access_token == '12345' + end end def context @@ -50,9 +54,9 @@ def sample_auth(*scopes) describe 'a guarded api endpoint' do before :all do class GuardedMountedApi < Grape::API - access_token_valid = proc { |token = nil| token.nil? || token != '12345' } + resource_owner_valid = proc { |token_owner = nil| token_owner.nil? } - desc 'Show endpoint if authenticated', hidden: access_token_valid + desc 'Show endpoint if authenticated', hidden: resource_owner_valid get '/auth' do { foo: 'bar' } end @@ -62,7 +66,7 @@ class GuardedApi < Grape::API mount GuardedMountedApi add_swagger_documentation endpoint_auth_wrapper: SampleAuth, swagger_endpoint_guard: 'sample_auth false', - oauth_token: 'access_token' + token_owner: 'resource_owner' end end