Migration from old versions

The intent of this document is to make migration of breaking changes as easy as possible. Please note that all breaking changes may not be included here. Please check the NEWS.md for a full list of changes before finalizing the upgrade process.

Newer versions

Follow latest changes (specially backwards incompatible ones, we follow semantic versioning) in the NEWS: https://github.com/doorkeeper-gem/doorkeeper/blob/master/NEWS.md.

From 4.x to 5.x

Database changes:

• Doorkeeper::Application now has a new boolean column named confidential that is true by default and has NOT NULL CONSTRAINT. This column is required to allow creating Public & Private Clients as mentioned in Section 8.5 of draft-ietf-oauth-native-apps-12 of OAuth 2 RFC which was previously unavailable. If you are migrating from the Doorkeeper <= 5.0, then you can easily add this column by generating a proper migration file using the following command: rails g doorkeeper:confidential_applications.

  [IMPORTANT]: all the applications (clients) starting from 5.0 / 4.4.x releases are considered as private by default. You need to manually change confidential column to false if you are using public clients, otherwise your mobile or other applications will not be able to authorize. See #1142 for more details.

API changes:

• [IMPORTANT]: Doorkeeper JSON responses changed: scopes field was replaced with scope, expires_in_seconds to expires_in to be consistent and match the RFC.
• Doorkeeper#configured?, Doorkeeper#database_installed?, and Doorkeeper#installed? methods were removed, so any Doorkeeper ORM extension doesn't need to support these methods starting from 5.0.
• Many memoized and other instance variables (like @token in doorkeeper_token method for Doorkeeper::Helpers::Controller) were renamed during refactoring, so if you are using them — just don't do it and call the original methods (helpers, etc) in order to get the required value.
• Test suite now has a refactored infrastructure: spec_helper_integration now renamed to industry-standard spec_helper.
• custom_access_token_expires_in option now provides a Doorkeeper::OAuth::Authorization::Context object (|context|) instead of raw params (|client, grant_type, scopes|). The context object has all these variables and you can access them in the block (like context.grant_type or context.client).
• admin_authenticator block now returns "403 Forbidden" response by default if developer didn't declare another behavior explicitly.
• Previously authorization code response route was /oauth/authorize/<code>, now it is oauth/authorize/native?code=<code> (in order to help applications to automatically find the code value).

Other changes:

• Bootstrap CSS was updated from 3.x to 4.0.

From 4.x to 4.4.x

API changes:

• [IMPORTANT]: 4.4.x release includes backport security fix from 5.x for token revocation when using public clients, so starting from this version all the applications (clients) are considered as private by default. You need to manually change confidential column to false if you are using public clients, otherwise your mobile (or other) applications will not be able to authorize. See #1142 for more details.

From 4.x to 4.3.x

API changes:

• FactoryGirl changed to FactoryBot.
• Previously authorization code response route was /oauth/authorize/<code>, now it is oauth/authorize/native?code=<code> (in order to help applications to automatically find the code value).

From 2.x to 3.x

API changes:

• MongoDB adapter extracted to its own extension.
• doorkeeper_unauthorized_render_options(error:) and doorkeeper_forbidden_render_options(error:) now accept error keyword argument.

From 1.x to 2.x

Database changes:

• Added scopes column to applications. Add it with rails generate doorkeeper:application_scopes generator.

API changes:

• doorkeeper_for DSL was changed to before_action :dorkeeper_authorize!.
• test_redirect_uri option renamed to native_redirect_uri.
• mount Doorkeeper::Engine now replaced with use_doorkeeper routes helper.

From 0.4.x to 0.5.x

Rails engine:

Doorkeeper is not an isolated engine anymore. Which means that most of the paths and old related engine methods won't work. Here's a list of things that changed:

• mount Doorkeeper::Engine won't work. Replace it with use_doorkeeper in your config/routes.rb file.
• All route paths have changed. If you generated all views, or use custom ones, you'll have to prepend oauth_ to each of them:

# also applies to prefixes (edit_ and new_)
authorized_applications(_path|_url) => oauth_authorized_applications(_path|_url)
applications(_path|_url)            => oauth_applications(_path|_url)
authorization(_path|_url)           => oauth_authorization(_path|_url)

API changes:

• The locale file has been updated. You'll need to reinstall the file with rails g doorkeeper:install (ignore other existing files) to ensure the gem works properly.
• Authorization code is now configurable:

authorization_code_expires_in 10.minutes

From 0.3.x to 0.4.x

Database changes:

The column resource_owner_id accepts null values, since we now support the Client Credentials flow.

change_column :oauth_access_tokens, :resource_owner_id, :integer, :null => true

API changes:

Scopes

Two things were changed in scopes

• The configuration for scopes has changed. You now have to use default_scopes and optional_scopes instead of the authorization_scopes block:

Doorkeeper.configure do
  default_scopes  :public
  optional_scopes :write, :update
end

• You have to translate your scopes in your application's locale file(s).

en:
  doorkeeper:
    scopes:
      public: "Access your public data"
      write:  "Update your data"

From 0.2.x to 0.3.x

Database changes:

Add indexes to database:

class UpgradeToVersion03 < ActiveRecord::Migration
  def change
    add_index :oauth_applications, :uid, :unique => true
    add_index :oauth_access_grants, :token, :unique => true
    add_index :oauth_access_tokens, :token, :unique => true
    add_index :oauth_access_tokens, :resource_owner_id
    add_index :oauth_access_tokens, :refresh_token, :unique => true
  end
end

From 0.1.x to 0.2.x

API changes:

• doorkeeper_for does not accept the :all option anymore.
• doorkeeper_for only accepts :except option when :all was specified.

Database changes:

class UpgradeToVersion02 < ActiveRecord::Migration
  def change
    add_column :oauth_access_grants, :scopes, :string

    # If you are upgrading from version 0.1.0, uncomment the line below.
    # add_column :oauth_access_grants, :revoked_at, :datetime

    add_column    :oauth_access_tokens, :refresh_token, :string
    add_column    :oauth_access_tokens, :scopes,        :string
    add_column    :oauth_access_tokens, :expires_in,    :integer
    remove_column :oauth_access_tokens, :expires_at
  end
end