Migration from old versions

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. If you are migrating from the Doorkeeper <= 5.0, then you can easily add this column by generating proper migration file using the following command: rails g doorkeeper:confidential_applications

API changes:

• Doorkeeper#configured?, Doorkeeper#database_installed?, and Doorkeeper#installed? methods was removed, so any Doorkeeper ORM extension don't need to support this 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 original methods (helpers, etc) in order to get the required value.
• Test suite now has refactored infrastructure: spec_helper_integration now renamed to industry-standard spec_helper.
• custom_access_token_expires_in option now provides Doorkeeper::OAuth::Authorization::Context object (|context|) instead of raw params (|client, grant_type, scopes|). Context object has all this 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 declared another behavior.

Other changes:

• Bootstrap CSS was updated from 3.x to 4.0

From 4.x to 4.3.x

API changes:

• FactoryGirl changed to FactoryBot.

From 2.x to 3.x

API changes:

• MongoDB adapter extracted to it's 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 to 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 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 of 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 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 into a your application's locale file.

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