This library implements an OpenID Connect authentication provider for Rails applications on top of the Doorkeeper OAuth 2.0 framework.
OpenID Connect is a single-sign-on and identity layer with a growing list of server and client implementations. If you're looking for a client in Ruby check out omniauth_openid_connect.
Full documentation lives in the wiki.
The following parts of OpenID Connect Core 1.0 and related specifications are currently supported:
- Authentication using the Authorization Code Flow
- Authentication using the Implicit Flow
- Requesting Claims using Scope Values
- UserInfo Endpoint
- Normal Claims
- OAuth 2.0 Form Post Response Mode
- OAuth 2.0 Dynamic Client Registration Protocol
- RP-Initiated Logout 1.0 client metadata — per-client
post_logout_redirect_urisregistration and validation; see RP-Initiated Logout for the host application's part - RFC 9207
issauthorization response parameter, emitted when Doorkeeper itself is configured with anissuer - RFC 8414 Authorization Server Metadata — see Routes for how this interacts with the metadata endpoint Doorkeeper 6.0 serves itself
In addition, we also support most of OpenID Connect Discovery 1.0 for automatic configuration discovery.
Take a look at the DiscoveryController for more details on supported features.
| Dependency | Supported versions |
|---|---|
| Ruby | 3.2 or newer |
| Rails | 7.0 to 8.1 |
| Doorkeeper | 5.5 or newer, below 7.0 |
| ORM | Active Record only |
The CI matrix is the authoritative statement of what is tested: each Rails series above against Ruby 3.2 through 4.0 and — except for Rails 7.0 — against ruby-head, plus one build per supported Doorkeeper series and one against Doorkeeper's main branch.
Make sure your application is already set up with Doorkeeper.
Add this line to your application's Gemfile and run bundle install:
gem 'doorkeeper-openid_connect'Run the installation generator to update routes and create the initializer:
rails generate doorkeeper:openid_connect:installGenerate a migration for Active Record (other ORMs are currently not supported):
rails generate doorkeeper:openid_connect:migration
rails db:migrateIf you're upgrading from an earlier version, check Migration from Old Versions wiki and CHANGELOG.md for upgrade instructions, including the migrations that newer versions add to existing installations.
Configuration and usage are documented in the wiki, whose home page indexes every topic. The pages to start from:
- Configuration — the issuer, subject, signing keys, and every other initializer option
- Migration from Old Versions — upgrade instructions for breaking changes
- Troubleshooting — symptoms, causes, and fixes for common integration pitfalls
The remaining pages cover scopes and claims, prompt and max_age, routes and multiple mounts, nonces, RP-Initiated Logout, Dynamic Client Registration, and I18n.
Run bundle install to setup all development dependencies.
To run all specs:
bundle exec rake specTo generate and run migrations in the test application:
bundle exec rake migrateTo run the local engine server:
bundle exec rake serverTo run the browser end-to-end tests, which boot the dummy app with Capybara and drive its dashboard through Cuprite:
bundle exec rake e2eThey need an installed Chrome or Chromium and nothing else. Run them with
HEADLESS=false to watch a flow in a visible browser. The suite boots the app
in the development environment against its own spec/dummy/db/e2e.sqlite3
database, so it leaves the one behind bundle exec rake server alone, and it
saves the page of a failing example to spec/dummy/tmp/e2e.
By default, Rails 8.0 is used. To use a specific version run:
rails=7.2 bundle updateDoorkeeper::OpenidConnect is released under the MIT License.
Initial development of this project was sponsored by PlayOn! Sports.