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.

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 he 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_scope :public

  # other available scopes
  optional_scope :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 you 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 the any of the scopes passed, then you'll get a 401 unauthorized response.

class ProtectedResourcesController < AppliactionController
  doorkeeper_for :index, :show,    :scopes => [:public]
  doorkeeper_for :update, :create, :scopes => [:write]

  # Your actions
end

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 < AppliactionController
  doorkeeper_for :index, :show,    :scopes => [:public]
  doorkeeper_for :update, :create, :scopes => [: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 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.