Doorkeeper Guides

https://doorkeeper.gitbook.io/guides/
Admin
Doorkeeper is an oAuth2 provider built in Ruby, providing an oAuth2 provider that integrates with...
Tokens:6,540
Snippets:114
Trust Score:9.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Query documentation via HTTP GET

Source: https://doorkeeper.gitbook.io/guides/llms.txt

Perform an HTTP GET request to the documentation index to retrieve answers based on a specific question and optional goal.

```http
GET https://doorkeeper.gitbook.io/guides/orms/sequel.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### GET /guides/orms/sequel.md

Source: https://doorkeeper.gitbook.io/guides/llms.txt

Perform a natural language query against the documentation index to receive a direct answer and relevant excerpts.

```APIDOC
## GET /guides/orms/sequel.md

### Description
Perform an HTTP GET request on the documentation index with the `ask` parameter, and the optional `goal` parameter to retrieve documentation answers.

### Method
GET

### Endpoint
https://doorkeeper.gitbook.io/guides/orms/sequel.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question in natural language.
- **goal** (string) - Optional - Describes the broader end goal to tailor the answer.
```

--------------------------------

### Install Doorkeeper Gem

Source: https://doorkeeper.gitbook.io/guides

Add the Doorkeeper gem to your Gemfile to begin the installation process.

```ruby
gem 'doorkeeper'
```

--------------------------------

### Install Doorkeeper Dependency

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started.md

Add the Doorkeeper gem to the project's Gemfile.

```bash
bundle add doorkeeper
```

--------------------------------

### Generate PKCE migration

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/pkce-flow.md

Run this command to generate the necessary database migration for enabling PKCE support in Doorkeeper.

```bash
bundle exec rails generate doorkeeper:pkce
```

--------------------------------

### Initialize extension configuration

Source: https://doorkeeper.gitbook.io/guides/internals/creating-extensions.md

Apply the custom configuration settings within a Rails initializer.

```ruby
# config/initializers/your_extension.rb
YourExtension.configure do
  expiration_time 15.minutes
  skip_something true

  enforce_something
end
```

--------------------------------

### Run database migration

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/polymorphic-resource-owner.md

Execute the generated migration to apply schema changes to the database.

```bash
$ bundle exec rails db:migrate
```

--------------------------------

### Generate Doorkeeper Files

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started.md

Run the generator to create the initializer, routes, and locale files.

```bash
bundle exec rails generate doorkeeper:install
```

--------------------------------

### Implement a custom access token model

Source: https://doorkeeper.gitbook.io/guides/configuration/models.md

Demonstrates configuring a custom class name and defining the model with the required Doorkeeper mixin.

```ruby
Doorkeeper.configure do
  access_token_class "MyAccessToken"
  # ...
end

# app/models/my_access_token.rb
class MyAccessToken < ApplicationRecord
  include ::Doorkeeper::Orm::ActiveRecord::Mixins::AccessToken

  self.table_name = "hey_i_wanna_my_name"

  def destroy_me!
    destroy
  end
end
```

--------------------------------

### Generate Doorkeeper Migrations

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started.md

Create the database migration files required for OAuth2 tables.

```bash
$ bundle exec rails generate doorkeeper:migration
    create  db/migrate/20190324080634_create_doorkeeper_tables.rb
```

--------------------------------

### Create OAuth Application via Console

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/api-mode.md

Manually create an OAuth application in the console since the administration UI is disabled in API mode.

```ruby
Doorkeeper::Application.create(name: "MyApp", redirect_uri: "urn:ietf:wg:oauth:2.0:oob", scopes: ["read", "write"])
```

--------------------------------

### Generate migration for polymorphic columns

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/polymorphic-resource-owner.md

Run this command to generate the necessary migration for adding polymorphic columns to Doorkeeper tables.

```bash
$ bundle exec rails g doorkeeper:enable_polymorphic_resource_owner
```

--------------------------------

### Define a custom extension configuration class

Source: https://doorkeeper.gitbook.io/guides/internals/creating-extensions.md

Use the Doorkeeper::Config::AbstractBuilder to define custom configuration options and methods for your extension.

```ruby
class YourExtension
  def self.configure(&block)
    @config = Config::Builder.new(Config.new, &block).build
  end

  def self.configuration
    @config || (raise Errors::MissingConfiguration)
  end

  class Config
    class Builder < Doorkeeper::Config::AbstractBuilder
      # your custom config methods
      def enforce_something
        @config.instance_variable_set(:@enforce_something, true)
      end
    end

    def enforce_something?
      if defined?(@enforce_something)
        @enforce_something
      else
        false
      end
    end

    # In case you defined some other builder class
    def self.builder_class
      Config::Builder
    end

    extend Doorkeeper::Config::Option

    # your custom options
    option :expiration_time, default: 1.hour
    option :skip_something, default: true
  end
end
```

--------------------------------

### Run database cleanup task

Source: https://doorkeeper.gitbook.io/guides/internals/rake.md

Executes the general cleanup task to remove stale access tokens and grants from the database.

```bash
rake doorkeeper:db:cleanup
```

--------------------------------

### Configure custom access token generator

Source: https://doorkeeper.gitbook.io/guides/configuration/other-configurations.md

Specify a custom class that responds to .generate to override the default 128-bit token generation.

```ruby
Doorkeeper.configure do
  access_token_generator "Doorkeeper::JWT"
end
```

--------------------------------

### Configure Global Authorization Bypass

Source: https://doorkeeper.gitbook.io/guides/configuration/skip-authorization.md

Set the skip_authorization block to return true to automatically approve all applications.

```ruby
skip_authorization do
  true
end
```

--------------------------------

### Configure Admin Application Management

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/configuration.md

Sets up the admin authenticator to control access to the OAuth applications management interface.

```ruby
Doorkeeper.configure do
  admin_authenticator do |_routes|
    current_user || warden.authenticate!(scope: :user)
  end
end
```

--------------------------------

### Run specific cleanup tasks

Source: https://doorkeeper.gitbook.io/guides/internals/rake.md

Individual tasks for granular control over which types of stale records to remove from the database.

```bash
rake doorkeeper:db:cleanup:revoked_tokens
rake doorkeeper:db:cleanup:expired_tokens
rake doorkeeper:db:cleanup:revoked_grants
rake doorkeeper:db:cleanup:expired_grants
```

--------------------------------

### Enable token secret hashing with fallback

Source: https://doorkeeper.gitbook.io/guides/security/token-and-application-secrets.md

Configures token hashing while allowing existing plain-text tokens to be validated and upgraded.

```ruby
  hash_token_secrets fallback: :plain
```

--------------------------------

### Enable BCrypt for application secrets

Source: https://doorkeeper.gitbook.io/guides/security/token-and-application-secrets.md

Configures application secrets to use BCrypt hashing, which is recommended for password-like security but introduces latency.

```ruby
  hash_application_secrets using: '::Doorkeeper::SecretStoring::BCrypt'
```

--------------------------------

### Configure Doorkeeper Scopes

Source: https://doorkeeper.gitbook.io/guides/configuration/scopes.md

Define default and optional scopes in the Doorkeeper initializer.

```ruby
Doorkeeper.configure do
  default_scopes :public # if no scope was requested, this will be the default
  optional_scopes :admin, :write
end
```

--------------------------------

### Enable application secret hashing with fallback

Source: https://doorkeeper.gitbook.io/guides/security/token-and-application-secrets.md

Configures application secret hashing while allowing existing plain-text secrets to be validated and upgraded.

```ruby
  hash_application_secrets fallback: :plain
```

--------------------------------

### Configure Doorkeeper for API Mode

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/api-mode.md

Enable API-only mode in the Doorkeeper initializer to skip UI controllers and CSRF protections.

```ruby
Doorkeeper.configure do
  api_only
  base_controller 'ActionController::API'
end
```

--------------------------------

### Configure custom base controller

Source: https://doorkeeper.gitbook.io/guides/configuration/other-configurations.md

Change the base controller that Doorkeeper inherits from to maintain application context.

```ruby
Doorkeeper.configure do
  base_controller 'ApplicationController'
end
```

--------------------------------

### Configure custom base metal controller

Source: https://doorkeeper.gitbook.io/guides/configuration/other-configurations.md

Override the default ActionController::API base for Doorkeeper's metal controller.

```ruby
Doorkeeper.configure do
  base_metal_controller 'ApplicationController'
end
```

--------------------------------

### Configure Foreign Keys in Migration

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started.md

Uncomment these lines in the generated migration file to enforce data integrity with the users table.

```ruby
# Uncomment below to ensure a valid reference to the resource owner's table
add_foreign_key :oauth_access_grants, :users, column: :resource_owner_id
add_foreign_key :oauth_access_tokens, :users, column: :resource_owner_id
```

--------------------------------

### Configure Conditional Authorization Bypass

Source: https://doorkeeper.gitbook.io/guides/configuration/skip-authorization.md

Use the resource_owner and client arguments to define custom logic for skipping the authorization screen.

```ruby
skip_authorization do |resource_owner, client|
  client.superapp? || resource_owner.admin?
end
```

--------------------------------

### Enable polymorphic resource owner in Doorkeeper configuration

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/polymorphic-resource-owner.md

Add the configuration option to your Doorkeeper initializer to enable polymorphic associations.

```ruby
Doorkeeper.configure do
  orm :active_record

  use_polymorphic_resource_owner
end
```

--------------------------------

### Enforce Scopes with AND Logic

Source: https://doorkeeper.gitbook.io/guides/configuration/scopes.md

Require an access token to have multiple specific scopes by chaining authorize calls.

```ruby
class Api::V1::ProductsController < Api::V1::ApiController
  before_action -> { doorkeeper_authorize! :public }, only: :index
  before_action only: [:create, :update, :destroy] do
    doorkeeper_authorize! :admin
    doorkeeper_authorize! :write
  end
end
```

--------------------------------

### Doorkeeper Mounted Routes List

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/routes.md

A list of the routes automatically mounted by the Doorkeeper gem.

```text
   native_oauth_authorization GET    /oauth/authorize/native(.:format)             doorkeeper/authorizations#show
          oauth_authorization GET    /oauth/authorize(.:format)                    doorkeeper/authorizations#new
                              DELETE /oauth/authorize(.:format)                    doorkeeper/authorizations#destroy
                              POST   /oauth/authorize(.:format)                    doorkeeper/authorizations#create
                  oauth_token POST   /oauth/token(.:format)                        doorkeeper/tokens#create
                 oauth_revoke POST   /oauth/revoke(.:format)                       doorkeeper/tokens#revoke
             oauth_introspect POST   /oauth/introspect(.:format)                   doorkeeper/tokens#introspect
           oauth_applications GET    /oauth/applications(.:format)                 doorkeeper/applications#index
                              POST   /oauth/applications(.:format)                 doorkeeper/applications#create
        new_oauth_application GET    /oauth/applications/new(.:format)             doorkeeper/applications#new
       edit_oauth_application GET    /oauth/applications/:id/edit(.:format)        doorkeeper/applications#edit
            oauth_application GET    /oauth/applications/:id(.:format)             doorkeeper/applications#show
                              PATCH  /oauth/applications/:id(.:format)             doorkeeper/applications#update
                              PUT    /oauth/applications/:id(.:format)             doorkeeper/applications#update
                              DELETE /oauth/applications/:id(.:format)             doorkeeper/applications#destroy
oauth_authorized_applications GET    /oauth/authorized_applications(.:format)      doorkeeper/authorized_applications#index
 oauth_authorized_application DELETE /oauth/authorized_applications/:id(.:format)  doorkeeper/authorized_applications#destroy
             oauth_token_info GET    /oauth/token/info(.:format)                   doorkeeper/token_info#show
```

--------------------------------

### Configure default Doorkeeper models

Source: https://doorkeeper.gitbook.io/guides/configuration/models.md

Sets the default model classes used by Doorkeeper's ActiveRecord ORM in the initializer.

```ruby
# app/initializers/doorkeeper.rb

Doorkeeper.configure do 
  access_token_class "Doorkeeper::AccessToken"
  access_grant_class "Doorkeeper::AccessGrant"
  application_class "Doorkeeper::Application"
end
```

--------------------------------

### OAuth2 Application Management

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/routes.md

Endpoints for managing OAuth2 client applications.

```APIDOC
## GET /oauth/applications

### Description
Lists all registered OAuth2 applications.

### Method
GET

## POST /oauth/applications

### Description
Registers a new OAuth2 application.

### Method
POST

## GET /oauth/applications/:id

### Description
Retrieves details for a specific OAuth2 application.

### Method
GET

## PUT/PATCH /oauth/applications/:id

### Description
Updates an existing OAuth2 application.

### Method
PUT, PATCH

## DELETE /oauth/applications/:id

### Description
Deletes an OAuth2 application.

### Method
DELETE
```

--------------------------------

### Load Doorkeeper Rake tasks

Source: https://doorkeeper.gitbook.io/guides/internals/rake.md

Add this line to your Rakefile to make Doorkeeper tasks available in your application.

```ruby
Doorkeeper::Rake.load_tasks
```

--------------------------------

### Implement a Route Constraint with Doorkeeper

Source: https://doorkeeper.gitbook.io/guides/configuration/route-constraints-and-other-integrations.md

Use this constraint to restrict access to routes based on the validity of an OAuth token extracted from the request.

```ruby
module Constraint
  class Authenticated

    def matches?(request)
      token = Doorkeeper.authenticate(request)
      token&.accessible?
    end
  end
end
```

--------------------------------

### Protecting API Controllers with Doorkeeper

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/protecting-your-resources.md

Use the doorkeeper_authorize! before_action to enforce OAuth token requirements on controller actions.

```ruby
class Api::V1::ProductsController < Api::V1::ApiController
  before_action :doorkeeper_authorize! # Requires access token for all actions
  
  # before_action -> { doorkeeper_authorize! :read, :write }

  # your actions
end
```

--------------------------------

### Protecting Grape API with Doorkeeper

Source: https://doorkeeper.gitbook.io/guides/grape/grape.md

Requires the Doorkeeper Grape helpers and inclusion of the helper module within the Grape API class to enable OAuth authorization.

```ruby
require 'doorkeeper/grape/helpers'

module API
  module V1
    class Users < Grape::API
      helpers Doorkeeper::Grape::Helpers

      before do
        doorkeeper_authorize!
      end

      # For old versions of Grape:
      #   route_setting :scopes, ['user:email']
      #
      get :me, scopes: [:user, :read] do
        current_user.to_json
      end

      # ...
    end
  end
end
```

--------------------------------

### Configure Resource Owner Authentication

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/configuration.md

Defines how users are authenticated for Doorkeeper, utilizing Devise's warden helper.

```ruby
Doorkeeper.configure do
  resource_owner_authenticator do
    current_user || warden.authenticate!(scope: :user)
  end
end
```

--------------------------------

### Enforce Scopes with OR Logic

Source: https://doorkeeper.gitbook.io/guides/configuration/scopes.md

Require an access token to have at least one of the specified scopes using a single authorize call.

```ruby
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
```

--------------------------------

### OAuth2 Authorization Endpoints

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/routes.md

Endpoints for handling OAuth2 authorization flows.

```APIDOC
## GET /oauth/authorize

### Description
Displays the authorization form for the user to approve or deny access.

### Method
GET

## POST /oauth/authorize

### Description
Processes the authorization request.

### Method
POST

## DELETE /oauth/authorize

### Description
Denies the authorization request.

### Method
DELETE
```

--------------------------------

### Associate User Model with Doorkeeper

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/getting-started.md

Add associations to the User model to manage access grants and tokens, preventing foreign key errors during deletion.

```ruby
class User < ApplicationRecord
  has_many :access_grants,
           class_name: 'Doorkeeper::AccessGrant',
           foreign_key: :resource_owner_id,
           dependent: :delete_all # or :destroy if you need callbacks

  has_many :access_tokens,
           class_name: 'Doorkeeper::AccessToken',
           foreign_key: :resource_owner_id,
           dependent: :delete_all # or :destroy if you need callbacks
end
```

--------------------------------

### Mount Doorkeeper Routes in Rails

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/routes.md

Add the use_doorkeeper method to the Rails application routes file to enable OAuth functionality.

```ruby
Rails.application.routes.draw do
  use_doorkeeper
  # your routes below
end
```

--------------------------------

### OAuth2 Token Endpoints

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/routes.md

Endpoints for token issuance, revocation, and introspection.

```APIDOC
## POST /oauth/token

### Description
Exchanges authorization grants or credentials for an access token.

### Method
POST

## POST /oauth/revoke

### Description
Revokes an existing access or refresh token.

### Method
POST

## POST /oauth/introspect

### Description
Returns information about the status of an access token.

### Method
POST

## GET /oauth/token/info

### Description
Retrieves information about the current access token.

### Method
GET
```

--------------------------------

### Accessing the Authenticated Resource Owner

Source: https://doorkeeper.gitbook.io/guides/ruby-on-rails/protecting-your-resources.md

Define a helper method to retrieve the user associated with the current access token using doorkeeper_token.

```ruby
class Api::V1::CredentialsController < Api::V1::ApiController
  before_action :doorkeeper_authorize!
  respond_to    :json

  # GET /me.json
  def me
    respond_with current_resource_owner
  end

  private

  # Find the user that owns the access token
  def current_resource_owner
    User.find(doorkeeper_token.resource_owner_id) if doorkeeper_token
  end
end
```

--------------------------------

### Specify custom secret transformer implementation

Source: https://doorkeeper.gitbook.io/guides/security/token-and-application-secrets.md

Overrides the default SHA256 hashing strategy with a custom implementation class.

```ruby
  hash_token_secrets using: '::My::Other::SecretStoring::Implementation'
```
Tokens:
Raw