rails-oidc_provider
This repository is a new gem (
rails-oidc_provider), historically derived from brandnewbox/oidc_provider. It is not an official continuation of that project. The maintainers of the original gem were unresponsive; this codebase packages the engine under a new name with its own release line, tests, and CI.The public Ruby API remains
OIDCProvider(engine, models, configuration) so existing applications can migrate with minimal code changes. Prefer theRailsOidcProvideralias for new code when you want the new gem identity.
A Rails engine that turns a host application into an OpenID Connect
provider, built on openid_connect.
Requirements
- Ruby >= 3.1
- Rails >= 7.0
- A host-app authentication stack exposing
authenticate_user!,current_user, andsign_out(Devise is the usual choice; the dummy app uses a minimal session equivalent for tests)
Installation
Add this line to your application's Gemfile:
gem 'rails-oidc_provider'Bundler.require loads the engine automatically (hyphenated gem name maps to
rails-oidc_provider / rails/oidc_provider entrypoints). You can also require
explicitly with require 'rails_oidc_provider' or require 'oidc_provider'.
Then:
bundle install
rails generate oidc_provider:install
rails oidc_provider:install:migrations
rails db:migrateThe install generator still writes config/initializers/oidc_provider.rb and
mounts:
mount OIDCProvider::Engine, at: '/accounts/oauth'
get '/.well-known/:id', to: 'oidc_provider/discovery#show'Migrating from oidc_provider
- Replace
gem 'oidc_provider', ...withgem 'rails-oidc_provider'. - Keep
OIDCProvider.configureand existing mounts/migrations — table names and theOIDCProviderconstant are unchanged. - Optionally start using
RailsOidcProvider.configure(delegates to the same API).
Private key
ID tokens are signed with an RSA private key at lib/oidc_provider_key.pem in the
host app (override with OIDC_PROVIDER_PRIVATE_KEY_PATH). Passphrase:
OIDC_PROVIDER_KEY_PASSPHRASE.
rails oidc_provider:generate_keyConfiguration
OIDCProvider.configure do |config|
config.issuer = 'https://www.example.com'
config.account_class = 'User'
config.add_client do
name 'Test Client'
identifier '0001'
secret 'secret'
redirect_uri 'https://app.example.com/oidc/callback'
end
config.add_scope OIDCProvider::Scopes::Profile do |user|
name user.full_name
given_name user.first_name
family_name user.last_name
end
config.add_scope OIDCProvider::Scopes::Email do |user|
email user.email
email_verified true
end
endRunning tests with Docker
The suite runs against a SQLite dummy Rails app inside Docker so you do not need a local Ruby/Rails toolchain matching CI.
One Ruby × Rails pair
# Defaults: Ruby 3.3 × Rails 7.1
bin/test-matrix
# Explicit pair
bin/test-matrix 3.2 7.2
bin/test-matrix --rubocop 3.3 7.1
# Compose equivalent (MATRIX_* avoids clashing with host rbenv RUBY_VERSION)
MATRIX_RUBY=3.2 MATRIX_RAILS=7.2 docker compose build test
MATRIX_RUBY=3.2 MATRIX_RAILS=7.2 docker compose run --rm test
# RuboCop in the test image
docker compose run --rm test bundle exec rubocopFull local matrix
bin/test-matrix --allSupported pairs match CI: Ruby 3.1–3.3 × Rails 7.0/7.1/7.2/8.0 (compatible only).
Without Docker
RAILS_VERSION=7.1 bundle install
OIDC_PROVIDER_KEY_PASSPHRASE=test-passphrase bundle exec rake app:db:prepare
OIDC_PROVIDER_KEY_PASSPHRASE=test-passphrase bundle exec rspec
bundle exec rubocopContinuous integration
GitHub Actions (.github/workflows/ci.yml) on master PRs/pushes:
- RSpec matrix — Ruby × Rails pairs (see workflow)
- RuboCop — Ruby 3.3 / Rails 7.1
-
Docker smoke —
bin/test-matrix 3.3 7.1
Releasing to RubyGems.org
Publishing is done by CI when you push a version tag (v*). Prefer
Trusted Publishing (OIDC) over
long-lived API keys.
One-time setup
-
Create an account on rubygems.org (enable MFA).
-
Push the gem once if it does not exist yet (optional first bootstrap):
gem build rails-oidc_provider.gemspec gem push rails-oidc_provider-1.0.0.gem # prompts for credentials / OTP -
On the gem’s RubyGems page → Trusted publishers → add a GitHub provider. Fields must match the OIDC claims from
.github/workflows/release.ymlexactly:-
Organization or user:
Pharmony(GitHub owner; casing as on github.com) -
Repository:
rails-oidc_provider(repo name only — notPharmony/…) -
Workflow filename:
release.yml(basename only — not a path) -
Environment:
release(must matchenvironment: releasein the workflow)
Also create a GitHub Environment named
release(Settings → Environments) if it does not exist. No protection rules are required for publishing to work; rules are optional extra gates.Common misconfig that yields
No trusted publisher configured for this workflow:- Environment set to
releaseon RubyGems but missing on the workflow (or the reverse) - Wrong repo name / owner casing /
owner/repostuffed into Repository - Workflow filename with a path (
/.github/workflows/release.yml)
-
Organization or user:
No RUBYGEMS_API_KEY secret is required when Trusted Publishing is configured.
Cut a release
- Bump
RailsOidcProvider::VERSIONinlib/rails_oidc_provider/version.rb. - Update
CHANGELOG.mdfor that version. - Commit and push
master. - Tag and push (triggers
.github/workflows/release.yml):Equivalent manual steps:bin/release # tags v$VERSION, pushes branch + tag bin/release --dry-run # show what would run
version=$(ruby -e "require_relative 'lib/rails_oidc_provider/version'; puts RailsOidcProvider::VERSION") git tag -a "v${version}" -m "Release v${version}" git push origin master git push origin "v${version}"
- Confirm the Release workflow is green. It will:
- publish the gem to https://rubygems.org/gems/rails-oidc_provider
- create a GitHub Release for the tag whose notes are the matching
section extracted from
CHANGELOG.md(and attach the built.gem)
The workflow fails if the tag (e.g. v1.0.1) does not match VERSION (1.0.1),
or if CHANGELOG.md has no ## [1.0.1] heading (notes fall back to a short
default message).
Local build only (no push)
bundle exec rake build # writes pkg/rails-oidc_provider-*.gem
bundle exec rake install # install into local gems for smoke testingLicense
The gem is available as open source under the terms of the MIT License.
Original engine copyright Brand New Box / contributors; this package continues
under MIT with additional maintenance copyright for the rails-oidc_provider
release line.