Doorkeeper::OpenidConnect

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.

Status
- Example Applications
Requirements
Installation
Documentation
Development
License
Sponsors

Status

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_uris registration and validation; see RP-Initiated Logout for the host application's part
RFC 9207 iss authorization response parameter, emitted when Doorkeeper itself is configured with an issuer
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.

Example Applications

Requirements

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.

Installation

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

Generate a migration for Active Record (other ORMs are currently not supported):

rails generate doorkeeper:openid_connect:migration
rails db:migrate

If 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.

Documentation

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.

Development

Run bundle install to setup all development dependencies.

To run all specs:

bundle exec rake spec

To generate and run migrations in the test application:

bundle exec rake migrate

To run the local engine server:

bundle exec rake server

To run the browser end-to-end tests, which boot the dummy app with Capybara and drive its dashboard through Cuprite:

bundle exec rake e2e

They 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 update

License

Doorkeeper::OpenidConnect is released under the MIT License.