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 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.

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.