# Doorkeeper: an OAuth 2 provider engine for Rails and Grape apps

> Doorkeeper is a Rails engine that adds OAuth 2 provider endpoints to an existing Ruby application. It ships the grant flows and token storage, but leaves cleanup, token format and identity extensions to you.

**doorkeeper-gem/doorkeeper** — Doorkeeper is an OAuth 2 provider for Ruby on Rails / Grape.

- Repository: https://github.com/doorkeeper-gem/doorkeeper
- Website: https://doorkeeper.gitbook.io/guides/
- Stars: 5,523 · Forks: 1,077
- Language: Ruby
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/doorkeeper-gem-doorkeeper

## The problem Doorkeeper solves inside an existing Rails app

Most teams that need OAuth 2 do not need a new service. They need the app they already run to hand out tokens to third-party clients, mobile apps, or their own single-page front end. Doorkeeper is aimed at exactly that: it is a gem, described in the README as a Rails engine, that adds OAuth 2 provider functionality to a Ruby on Rails or Grape application.

The audience is therefore narrow and specific. You need a Ruby codebase, a database, and a reason to be the authorization server rather than the client. If you are building a SaaS product and want customers to connect their own tools to your API, Doorkeeper is the layer that issues and validates the credentials. If you are writing a small internal script that consumes someone else's API, it is the wrong tool entirely; you want a client library, not a provider.

The README lists the supported surface: the authorization code flow, access token scopes, refresh tokens, implicit grant, resource owner password credentials, and client credentials. On top of the core framework it also covers token revocation, token introspection, the threat model document, native app guidance, PKCE, issuer identification and resource indicators. That is a wide protocol surface for a single gem, and it is the main reason to consider it rather than hand-rolling endpoints.

## How the engine plugs into your routes and models

The architecture follows the standard Rails engine pattern. The gem ships an app/ directory and a config/ directory, and mounting it in your router exposes the OAuth endpoints. Token and grant records live in your own database through Active Record, which is the default ORM. That means the authorization server shares a database with the rest of your application, and your existing user model becomes the resource owner.

The data flow for an authorization code exchange looks like this. A client redirects the user to the authorization endpoint, the user approves, and Doorkeeper creates a record in oauth_access_grants. The client then posts that code to the token endpoint, and the gem issues an access token plus a refresh token, stored in oauth_access_tokens. Scopes are attached to those records, so your API can check them on each request.

Two design choices are worth flagging. First, tokens are opaque database rows by default, not JWTs; JWT support is a separate extension, doorkeeper-jwt, listed under Extensions in the README. Second, OpenID Connect is also an extension, doorkeeper-openid_connect, not part of the core gem. If your clients expect an id_token or a discovery document, you are signing up for a second dependency.

ORM support beyond Active Record is handled by third-party adapters: doorkeeper-mongodb, doorkeeper-sequel, doorkeeper-couchbase and doorkeeper-rethinkdb. Those are maintained outside this repository, so the maintenance burden shifts to whoever owns the adapter.

## Installing the Doorkeeper gem and issuing a first token

Installation starts in the Gemfile. The README gives this exact line, followed by bundle install:

```ruby
gem 'doorkeeper'
```

After that, the README points to framework-specific guides rather than inline steps. For Rails it states that Doorkeeper supports Ruby on Rails >= 5.0 and links to the getting started guide at doorkeeper.gitbook.io. For Grape there is a separate guide. The repository itself carries the usual Rails engine machinery: a Rakefile, a gemspec, generators under lib/, and a spec/dummy application used for testing, which is a reasonable place to look when the guides leave a gap.

Once the engine is mounted and migrations have been run, the operational command you will use most is the cleanup task. The README documents it explicitly:

```bash
bundle exec rake doorkeeper:db:cleanup
```

This deletes expired and revoked access tokens and grants. Running it on a schedule is not optional in practice; the README states plainly that Doorkeeper does not automatically remove expired or revoked tokens and grants, and that the oauth_access_tokens and oauth_access_grants tables grow indefinitely.

For a containerised development environment, the repository includes a Dockerfile based on ruby:3.3.4-alpine. It defines UID, GID and TZ build arguments, installs bundler 2.5.11, and sets the default command to rake. That image is built for working on Doorkeeper itself, not for deploying your application, so do not mistake it for a production template.

## Token tables grow forever unless you prune them

The most concrete limitation in the README is the database growth problem. Every issued access token and every grant is a row, and nothing removes them on its own. The README warns the tables can reach millions of rows if left unmanaged. On a busy authorization server that is not a hypothetical; it is the expected trajectory.

The bundled rake task is the documented answer, and it deletes expired and revoked records. What the README does not give is a scheduling mechanism. There is no built-in cron, no Active Job integration, no retention policy beyond expiry and revocation. You supply the scheduler, and you decide how often to run it. That is a real operational cost that a smaller app can absorb and a large one cannot ignore.

The second limitation is the default token format. Because access tokens are database-backed by default, every API request that validates a token is a database lookup unless you add caching or switch to JWT through doorkeeper-jwt. Teams coming from stateless JWT-based systems often assume the opposite and are surprised by the query volume.

A third boundary is identity. Doorkeeper is an OAuth 2 provider, not an identity provider. The README lists OpenID Connect as an extension, which means userinfo endpoints, ID tokens and discovery metadata are out of scope for the core gem. If a client asks for OpenID Connect, you are integrating a second project.

## Doorkeeper compared with running a standalone authorization server

The alternative most teams weigh against Doorkeeper is a separate identity service such as Keycloak, or a hosted provider. The difference is architectural, not cosmetic. A standalone server is its own deployment: its own database, its own admin console, its own upgrade cycle, and its own network hop between your application and the token issuer. Doorkeeper runs inside your application process and writes to your existing database, so there is no second service to operate and no cross-service consistency problem when a user is deleted.

The trade-off runs the other way too. A standalone server gives you OpenID Connect, a management UI and multi-tenant configuration without writing Ruby. Doorkeeper gives you none of that out of the box; the README lists OpenID Connect, JWT, assertion grants, I18n and CIBA as separate extensions, each with its own repository and release cadence. If you need those features and do not want to maintain several gems, the standalone route is shorter.

A second comparison is hand-rolling the endpoints. Doorkeeper covers RFC 6749 flows plus RFC 7009 revocation, RFC 7662 introspection, RFC 7636 PKCE, RFC 8252 native apps, RFC 8707 resource indicators and RFC 9207 issuer identification. Reproducing that set correctly, including the security considerations in RFC 6819, is a substantial amount of work that the gem has already done.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-22. Recent releases include v5.9.7 and v6.0.0.rc1, both dated 2026-09-10, with v5.9.6 before them on 2026-08-11. The presence of a release candidate alongside a patch release on the same day suggests a stable line and a next major line running in parallel.

Upgrades are documented rather than silent. The repository contains UPGRADE.md, CHANGELOG.md and NEWS.md, and the README links to a wiki page titled Migration from old versions. The README also warns that the documentation reflects the main branch and that you should check the documentation for the version you are using in the releases. That is a practical instruction: pin your reading to your installed version, not to main.

The licence is MIT, and the repository carries an MIT-LICENSE file. In practical terms that permits commercial use and modification with attribution and no warranty. This is a description of the licence text, not legal advice; if your organisation has specific compliance requirements, have counsel review it.

One maintenance detail worth noting: the README says the documentation is valid for main, while the guides live on GitBook. Two documentation sources with different versioning is a small but real source of confusion when you are debugging an upgrade.

## Conclusion

Adopt Doorkeeper if you already run a Rails or Grape app and need to issue OAuth 2 tokens to your own clients; skip it if you want a standalone identity server or OpenID Connect out of the box. Before committing, check that your Rails version is at least 5.0, decide how oauth_access_tokens will be pruned, and confirm whether your ORM is Active Record or needs a separate adapter gem.

## FAQ

### What is the Doorkeeper gem used for?

It is a Rails engine that adds OAuth 2 provider functionality to a Ruby on Rails or Grape application, so your app can issue and validate access tokens for clients.

### How do I install Doorkeeper in a Rails app?

Add gem 'doorkeeper' to your Gemfile and run bundle install, then follow the Ruby on Rails getting started guide linked from the README. Doorkeeper supports Ruby on Rails >= 5.0.

### Does Doorkeeper delete expired access tokens automatically?

No. The README states it does not automatically remove expired or revoked tokens and grants, and that the oauth_access_tokens and oauth_access_grants tables grow indefinitely. You run bundle exec rake doorkeeper:db:cleanup periodically to prune them.

### Does Doorkeeper support OpenID Connect or JWT tokens?

Not in the core gem. The README lists OpenID Connect and JWT token support as separate extensions, doorkeeper-openid_connect and doorkeeper-jwt, installed independently.

### What ORMs can Doorkeeper use besides Active Record?

Active Record is supported by default. MongoDB, Sequel, Couchbase and RethinkDB are supported through separate adapter gems listed in the README, each maintained outside this repository.

## Sources

- [doorkeeper-gem/doorkeeper on GitHub](https://github.com/doorkeeper-gem/doorkeeper)
- [License: MIT](https://github.com/doorkeeper-gem/doorkeeper/blob/main/LICENSE)
- [Project website](https://doorkeeper.gitbook.io/guides/)
- [README](https://github.com/doorkeeper-gem/doorkeeper/blob/main/README.md)
- [Releases](https://github.com/doorkeeper-gem/doorkeeper/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/doorkeeper-gem-doorkeeper