Purpose of scopes
Authorization scopes are a way to determine to what extent the client can use resources located in the provider.
When the client requests the authorization it specifies in which scope they would like to be authorized. This information is then displayed to the user - resource owner - and they can decide whether or not they accept the given application to be able to act in specified scopes.
Doorkeeper scopes
Doorkeeper scopes have an extra functionality which is the Default Scopes.
Default Scopes are the ones that are selected for authorizations that do not specify which scopes they need. In other words, if the client does not pass scope parameter in the authorization URI then these are the scopes that they will get assigned.
Note: In this situation the issued token will have an empty scopes attribute as well, so if you then add another default scope at a later date, previously issued tokens will automatically grant access to this scope as well. If you want to avoid this you can invalidate these tokens by deleting them from your database.
Usage (versions +0.4)
Configuration
Configure the scopes in initializers/doorkeeper.rb:
Doorkeeper.configure do # if no scope was requested, this will be the default default_scopes :public # other available scopes optional_scopes :admin, :write end
Translating scopes
To display a better message to the user (instead of just the scope name), it's very recommended that you translate your scopes into a locale file:
# config/locales/en.yml en: doorkeeper: scopes: public: 'Access your public data' write: 'Update your information' admin: 'Change your preferences'
Using in your API
You can specify which actions require a specific access token scope. If the access token does not contain any of the scopes passed, then you'll get a 401 Unauthorized response if token isn't accessible on invalid and 403 Forbidden if token scopes doesn't match required.
class Api::V1::ProductsController < Api::V1::ApiController before_action -> { doorkeeper_authorize! :public }, only: :index before_action only: [:create, :update, :destroy] do doorkeeper_authorize! :admin, :write end end
Limiting scopes per Application
A common use case is wanting to limit the scope(s) that your OAuth application can access (for example using your API for both end-users and an Admin Webapp. This can be achieved in Doorkeeper by adding to the scopes attribute in a space separated string like so:
Doorkeeper::Application.create!(
name: 'Test App',
uid: 'c0896b73c91687cf349606978cab3d2d614c8e1d52d5aa298c754e4b0',
secret: '303401b3363040a0a747689d2b316c813e1abbe021b29878fc48c432e6861d09c4d',
redirect_uri: 'urn:ietf:wg:oauth:2.0:oob',
scopes: 'admin mobile'
)
If the scopes field is not populated then the default_scopes from the Doorkeeper configuration will be used instead.
Usage (versions pre 0.4)
Configuration
Configure the scopes in initializers/doorkeeper.rb:
Doorkeeper.configure do # (...) other configuration authentication_scopes do scope :public, :default => true, :description => "Access your public data" scope :write, :description => "Update your data" scope :email, :description => "Send you an email" end end
The first argument of scope function is the identifier of the scope. Then you can specify additional options such as description or default.
Using in your API
In controllers accessed by OAuth users you along with the doorkeeper_for you need to pass an option :scopes that specify which access tokens can access that action:
class ProtectedResourcesController < ApplicationController doorkeeper_for :index, :show, :scopes => [:public] doorkeeper_for :update, :create, :scopes => [:write] # Definitions of actions end
The code above means that for index and show actions you need an access token with :public scope and for update and create you need access token with :write scope. You may also decide that as long as someone has :write scope they may as well see the data and use something like this:
doorkeeper_for :index, :show, :scopes => [:public, :write]
which means that as long as the access token has either :public or :write scope it can access index and show actions.
Requesting particular scopes
As a client, in order to specify which scopes you want you need to pass scope parameter while requesting authorization URI. Scope parameter is a space separated list of scopes you want to have associated with your access token. For example
http://provider.example.com/oauth/authorize?(... other params... )&scope=public+write
which would request public and write scopes.
All existing OAuth flows accept scope as parameter.