Doorkeeper Documentation

To use Doorkeeper as an OAuth 2 provider, add the gem to your Gemfile and run bundle install.

Depending on your framework, follow the specific integration guides:

• Ruby on Rails: Supports Rails >= 5.0.
• Grape: Requires specific integration steps for the Grape framework.

gem 'doorkeeper'

To run the test suite against a specific version of Rails, set the BUNDLE_GEMFILE environment variable to the desired gemfile.

Example for Rails 6.0:

BUNDLE_GEMFILE=gemfiles/rails_6_0.gemfile bundle exec rake

If you are developing with Doorkeeper or want to run the local engine server, use the following commands:

1. Install dependencies: bundle install
2. Start the server: bundle exec rake doorkeeper:server

You can define fine-grained logic to determine if a specific token is allowed to be introspected by configuring allow_token_introspection. This configuration accepts a proc that is called with the token, the auth_client (if using client authentication), and the auth_token (if using bearer token authentication).

This is useful for restricting introspection to specific clients or ensuring tokens can only be introspected by authorized resource servers.

You can customize the JSON response returned by the RFC 7662 Token Introspection endpoint by configuring custom_introspection_response in your Doorkeeper configuration. This block receives the token and the server.context (the controller context), allowing you to merge additional metadata into the introspection response.

If the block returns a blank value, the default response is used.

Doorkeeper implements the OAuth 2.0 Authorization Server Metadata response as described in RFC 8414. You can extend the default metadata response by providing a custom_metadata hash in your Doorkeeper configuration. This is useful for adding fields required by extensions like OpenID Connect (e.g., userinfo_endpoint).

Note that the userinfo_endpoint is intentionally returned as null by default to maintain backwards compatibility and should be populated via custom_metadata.

The following features can be added to Doorkeeper via separate gems:

• OpenID Connect extension: doorkeeper-gem/doorkeeper-openid_connect
• JWT Token support: doorkeeper-gem/doorkeeper-jwt
• Assertion grant extension: doorkeeper-gem/doorkeeper-grants_assertion
• I18n translations: doorkeeper-gem/doorkeeper-i18n
• CIBA (Client Initiated Backchannel Authentication Flow): doorkeeper-ciba
• Device Authorization Grant: doorkeeper-device_authorization_grant

Doorkeeper supports Active Record by default. For other databases, you must use specific adapter gems:

The Doorkeeper::OAuth::Client class delegates several attributes to the underlying application object. You can access the following methods directly on a client instance:

• id
• name
• uid
• redirect_uri
• scopes
• confidential