Using Scopes

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 he would like to be authorized. This information is then displayed to the user - resource owner - and he can decide whether or not he accepts given application to be able to act in specified scopes.

Usage

In order to start using scopes first you need to register them by passing authentication_scopes block in doorkeeper initializer:

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

The first argument of scope function is the identifier of the scope. Then you can specify additional options such as description or default (described later).

So the scopes are registered in the system but it is not the end yet. 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 < AppliactionController
  doorkeeper_for :index, :show, :scopes => [:public]
  doorkeeper_for :update, :create => [:write]

  # Definitions of actions
end

The code below 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 he 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 action.

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 paramaeter 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%20write

which would request public and write scopes.

Default scopes

The scopes defined with default flag set to true (which by "default" is false) are the ones that are selected for authorizations that do not specify which scopes they need. So if the client does not pass scope parameter in the authorization URI then these are the scopes that he will get assigned.