Sorceryは、Ruby on Railsにログイン機能を組み込むための軽量な認証gemです(英単語のsorcery=魔術や、ゲームブック『ソーサリー』の解説ではありません)。この記事では、最新の0.18.0をRails 8.1.4に入れて実際に動かしたコードで、ユーザー登録からログイン、ロック、OAuthまでを解説します。Qiitaなどの解説記事に多いredirect_back_or_toは、0.18.0では非推奨警告が出る書き方になっているので、その直し方も扱います。
まとめ:Sorcery 0.18.0を使う前に押さえる要点
- 最新は0.18.0(2025年12月6日公開・MIT)。動作要件はRuby 3.2以上・Rails 7.1以上で、mainブランチのCIはRails 7.1〜8.1とRuby 3.2〜4.0の組み合わせで回っています。
- 導入は「Gemfile追加 →
rails g sorcery:install→rails db:migrate」。Userモデルとauthenticates_with_sorcery!はジェネレータが作りますが、バリデーションと画面は自分で書きます。 - 元のページへ戻すリダイレクトは、
config.use_redirect_back_or_to_by_rails = trueを設定し、redirect_to_before_login_pathで書きます。旧来のredirect_back_or_toは非推奨警告が出ます。 - 追加機能はsubmoduleで足します。パスワードリセットのトークンは既定では有効期限がないため、
reset_password_expiration_periodを必ず設定します。 - OAuthは
authentications_classの設定が必須です。設定しないとNoMethodErrorで止まります。stateの生成と照合もSorceryはしないので、自分で書きます。 - 画面まで一式ほしいならDevise、DeviseやSorceryへの依存を避けたいならRails 8標準の認証ジェネレーター、自前の画面で認証の部品だけ借りたいならSorcery、という選び方になります。
Sorcery・Devise・Rails 8標準認証の違い
Sorceryはログイン処理やパスワードのハッシュ化をメソッドとして提供し、ビューやコントローラは生成しません。公式READMEは「公開メソッドは20個未満」「生成コードを持たない」ことを設計方針に掲げています。Railsで認証を組むときの比較相手は、Deviseと、Rails 8.0から入った標準の認証ジェネレーター(rails g authentication)です。
3つの選択肢の比較表
| 観点 | Sorcery 0.18.0 | Devise 5.0.4 | Rails 8標準ジェネレーター |
|---|---|---|---|
| 形態 | gem(メソッド提供) | gem(画面・ルート一式) | コード生成(bcryptを使用) |
| ビュー | 自作 | 自動生成 | ログイン・リセット画面を生成 |
| ユーザー登録 | 自作 | あり | なし(自作) |
| パスワードリセット | submodule | あり | あり(リンク15分) |
| アカウントロック | submodule | Lockable | なし(試行は3分10回まで) |
| OAuthログイン | submodule(20種の実装) | OmniAuth連携 | なし |
| セッション保存 | Railsのsession | Warden経由 | sessionsテーブル |
Rails 8の標準ジェネレーターは、Railsガイドのセキュリティの章に「ユーザー登録のコードは生成されない」と明記されています。Rails 8.1.4で実行すると、Sessionモデル、SessionsController、PasswordsControllerとemail_address・password_digestを持つusersテーブルのマイグレーションが作られました。DeviseはRails標準の上に別の規約を重ねるので、標準から外れた要件ではオーバーライド箇所を探す時間がかかります。Deviseの内部で使われている認証の仕組みはWardenのカスタム戦略の作り方で解説しています。
Sorceryを選ばないほうがよい場面
新規のRails 8アプリで、要件がメールとパスワードのログインとパスワードリセットだけなら、Sorceryを足す理由は薄く、標準ジェネレーターで足ります。依存gemが1つ減り、生成コードを読めば全体が見えるからです。管理画面を短期間で立ち上げる、メール確認・ロック・登録画面まで標準のまま揃えたい、という場合はDeviseのほうが書く量は少なくなります。Sorceryが向くのは、既存のSorcery採用アプリを保守する場合と、ロック・remember_me・OAuthなど標準ジェネレーターに無い部品を、自前の画面のまま足したい場合です。
メンテナンス状況と0.18.0の動作要件
Sorceryは2024年9月に、当時のメンテナが「Sorcery Unmaintained」とするプルリクエスト#376をマージし、一時は保守停止の状態でした。その後メンテナが交代し、0.18.0のリリースノートのとおり2025年12月6日に新版が出ています。0.18.0ではRuby 3.2未満とRails 7.1未満のサポートを打ち切り、form_authenticity_tokenメソッドを削除しました。RubyGems.org上の依存はbcrypt(~> 3.1)・oauth(>= 0.6)・oauth2(~> 2.0)・railties(>= 7.1)です。0.18.0のあとはタグが付いておらず、mainブランチへの最終コミットは2026年6月です。採用時は、過去のリリース間隔だけで今後の更新頻度を見積もらず、未解決のIssueと保守体制も確認してください。
Sorceryのインストールと初期設定
Ruby 4.0.6・Rails 8.1.4・sorcery 0.18.0の新規アプリで、登録・ログイン・ログアウト・ロック・remember_me・パスワード変更を検証しています。OAuthは、Googleの認可画面へのリダイレクト、state照合、ユーザー作成処理までを確かめたもので、Googleとのトークン交換は含みません。まずGemfileに追記してbundle installします。
gem 'sorcery', '~> 0.18.0'
続けてインストールジェネレータとマイグレーションを実行します。ジェネレータの基本的な使い方はRailsジェネレータ(rails generate)の使い方で解説しています。
bin/rails g sorcery:install
bin/rails db:migrate
実行すると、config/initializers/sorcery.rb、app/models/user.rb、usersテーブルのマイグレーションが作られます。usersテーブルはemail(NOT NULL・一意インデックス)、crypted_password、saltの3列です。Userモデルにはジェネレータがauthenticates_with_sorcery!を差し込みますが、バリデーションは入りません。次のように自分で足します。
class User < ApplicationRecord
authenticates_with_sorcery!
validates :email, presence: true, uniqueness: true
validates :password, length: { minimum: 8 }, if: -> { new_record? || changes[:crypted_password] }
validates :password, confirmation: true, if: -> { new_record? || changes[:crypted_password] }
validates :password_confirmation, presence: true, if: -> { new_record? || changes[:crypted_password] }
end
usersテーブルにpassword列はありません。passwordは仮想属性で、保存時にbcryptでハッシュ化されてcrypted_passwordに入ります。パスワードのバリデーションを「新規作成時か、パスワード変更時」に限るのは、メールアドレスだけを更新するときにパスワード入力を求めないためです。実測でも、この条件付きにしておけばupdate!(email: ...)はパスワードなしで通りました。
ユーザー登録とログイン・ログアウトの実装
Sorceryは画面を作らないので、ルーティング・コントローラ・フォームを用意します。ここでは「登録」「ログイン」「ログアウト」の3つを作ります。以下のコードに加えて、PagesControllerのhomeアクションと表示用ビュー、ユーザー登録用のnewビューを用意してください。
ルーティングとアクセス制限
Rails.application.routes.draw do
root "pages#home"
resources :users, only: [:new, :create]
get "login", to: "user_sessions#new"
post "login", to: "user_sessions#create"
delete "logout", to: "user_sessions#destroy"
end
全ページをログイン必須にし、未ログイン時の行き先を決めるのはApplicationControllerです。not_authenticatedは、Sorceryの既定ではroot_pathへリダイレクトするだけなので、ログイン画面へ送るように上書きします。
class ApplicationController < ActionController::Base
before_action :require_login
private
def not_authenticated
redirect_to login_path, alert: "ログインが必要です"
end
end
ユーザー登録(UsersController)
登録画面と登録処理はログイン前に開くので、skip_before_actionで除外します。登録後にauto_loginを呼ぶと、パスワードを再入力させずにログイン状態にできます。
class UsersController < ApplicationController
skip_before_action :require_login, only: [:new, :create]
def new
@user = User.new
end
def create
@user = User.new(user_params)
if @user.save
auto_login(@user)
redirect_to root_path, notice: "登録しました"
else
render :new, status: :unprocessable_entity
end
end
private
def user_params
params.require(:user).permit(:email, :password, :password_confirmation)
end
end
auto_loginは有効化状態を確認せず、セッションIDも作り直しません。後述のuser_activationを入れる場合は、登録後にauto_loginを呼ばず「確認メールを送りました」と案内してログイン画面へ戻します。登録直後にログインさせる構成でも、auto_loginの前にreset_sessionを呼んでおくとセッション固定攻撃を防げます。フォームはform_with model: @userで、email・password・password_confirmationの3項目を送ります。7文字のパスワードで送ると422、8文字以上なら302でroot_pathへ遷移しました。
ログイン・ログアウト(UserSessionsController)
loginは認証に成功するとユーザーを、失敗するとnilを返します。第3引数は後述のremember_me用です。
class UserSessionsController < ApplicationController
skip_before_action :require_login, only: [:new, :create]
def new
end
def create
if login(params[:email], params[:password], params[:remember_me] == "1")
redirect_to_before_login_path(root_path, notice: "ログインしました")
else
flash.now[:alert] = "メールアドレスかパスワードが違います"
render :new, status: :unprocessable_entity
end
end
def destroy
logout
redirect_to login_path, notice: "ログアウトしました", status: :see_other
end
end
ログインフォームはモデルを持たないのでform_with url: login_pathで書きます。
<%= form_with url: login_path do |f| %>
<%= f.label :email, "メールアドレス" %>
<%= f.email_field :email %>
<%= f.label :password, "パスワード" %>
<%= f.password_field :password %>
<%= f.check_box :remember_me %>
<%= f.label :remember_me, "ログインしたままにする" %>
<%= f.submit "ログイン" %>
<% end %>
失敗時にstatus: :unprocessable_entity(422)を返すのは、Turboがフォーム再描画を正しく扱うためです。ログアウトのstatus: :see_other(303)は、DELETEのあとのリダイレクト先をGETで開かせるためです。結合テストでは、未ログインで保護ページを開くと/loginへ302、正しいパスワードで元の保護ページへ302、ログアウトで303を返しました。
redirect_back_or_toの非推奨警告と元のページへ戻す設定
Rails 7.0で、Rails本体にもredirect_back_or_toという同名のメソッドが入りました。Sorceryのredirect_back_or_toはこれを上書きしているため、0.18.0では呼ぶたびに次の非推奨警告が出ます(lib/sorcery/controller.rb)。
DEPRECATION WARNING: `redirect_back_or_to` overrides the method of the same name defined in Rails 7.
To avoid overriding, set `config.use_redirect_back_or_to_by_rails = true` and use `redirect_to_before_login_path`.
In a future release, `config.use_redirect_back_or_to_by_rails = true` will become the default.
注意が要るのは、設定だけ変えて呼び出しをredirect_back_or_toのまま残した場合です。Rails版はリファラ(直前に開いていたページ)へ戻すので、ログインフォームから送信すると/loginに戻ってしまいます。保護ページ/secretを開いてからログインする流れで3通りを試した結果は次のとおりです。
| 設定値 | 呼び出すメソッド | 遷移先 | 警告 |
|---|---|---|---|
| false(既定) | redirect_back_or_to | /secret | あり |
| true | redirect_back_or_to | /login | なし |
| true | redirect_to_before_login_path | /secret | なし |
正解は3行目です。初期化ファイルのconfigureブロックに1行足し、コントローラの呼び出しをredirect_to_before_login_pathに置き換えます。将来の版で既定値がtrueに変わると予告されているので、今のうちに置き換えておけば、更新時に2行目の状態に落ちる事故を防げます。
Rails.application.config.sorcery.configure do |config|
config.use_redirect_back_or_to_by_rails = true
# ...
end
Sorceryの主要ヘルパーメソッドとnot_authenticated
コントローラとビューで使うメソッドは多くありません。検索で単体で調べられることの多いnot_authenticatedは、require_loginが未ログインを検知したときに呼ぶメソッドで、どのメソッドを呼ぶかはconfig.not_authenticated_actionで変えられます。
| メソッド | 動き |
|---|---|
| login(email, password, remember) | 成功でユーザー、失敗でnil |
| login!(email, password) | 失敗でSorcery::InvalidCredentials |
| logout | セッションを破棄 |
| auto_login(user) | パスワードなしでログイン |
| logged_in? / current_user | ログイン判定 / ログイン中のユーザー |
| require_login | before_action用。未ログインなら下へ |
| not_authenticated | 既定はroot_pathへリダイレクト |
| redirect_to_before_login_path(url) | 保存したURLかurlへ戻す |
require_loginは、GETかつAjaxでもJSONでもないリクエストのときだけ、開こうとしたURLをsession[:return_to_url]に保存します。POSTやJSON APIのリクエストでは戻り先URLが新たに保存されません。セッションに以前の戻り先URLも残っていなければ、ログイン後はredirect_to_before_login_pathの引数のURLへ飛びます。公開ページを持つコントローラではskip_before_action :require_login, only: [:index, :show]のように除外します。
submoduleの追加手順と既定値
パスワードリセットやロックなどは、submoduleとして必要なものだけ有効にします。ジェネレータに--only-submodulesを付けて実行すると、マイグレーションが作られ、初期化ファイルのsubmodulesの配列にも追記されます。
bin/rails g sorcery:install remember_me brute_force_protection --only-submodules
bin/rails db:migrate
このあとexternalを追加で実行すると、配列は[:remember_me, :brute_force_protection, :external]になりました。ジェネレータを使えば宣言漏れは起きません。初期化ファイルを手で書き換える場合は、submodules =を2回書くと後の代入で前の指定が消えるので、1つの配列にまとめます。同じことがUserモデル側の設定を書くconfig.user_configブロックにも当てはまります。Sorceryはこのブロックを1つしか保持しないため、生成された初期化ファイルにあるconfig.user_config do |user|とは別にもう1つ書くと、後から書いた方で前のブロックが丸ごと置き換わります。以降のコード例のuser.で始まる設定は、すべて既存の1つのブロックの中に書き足してください。各submoduleの既定値は、0.18.0のソースで次のとおりです。
| submodule | 機能 | 主な既定値 |
|---|---|---|
| remember_me | ログイン状態の保持 | 7日 |
| session_timeout | セッションの期限切れ | 3600秒(ログイン時刻から) |
| brute_force_protection | アカウントロック | 50回失敗で3600秒 |
| reset_password | パスワード再設定 | トークン期限なし/再送間隔300秒 |
| user_activation | メール認証 | 有効化前はログイン不可 |
| magic_login | パスワードなしログイン | トークン900秒 |
| http_basic_auth | Basic認証 | – |
| activity_logging | 最終ログイン等の記録 | – |
| external | OAuthログイン | authentications_classは未設定 |
remember_meによるログイン状態の保持
remember_meを有効にすると、usersテーブルにremember_me_tokenとremember_me_token_expires_atが加わります。loginの第3引数にtrueを渡すと、署名付きCookieremember_me_tokenが発行されます。実測では、チェックなしではCookieが発行されず、チェックありでは有効期限が約60万5,000秒(7日)後に設定されました。期間はuser.remember_me_for(秒)で変えます。
パスワードリセットとトークンの有効期限
reset_passwordで最も見落としやすいのは、reset_password_expiration_periodの既定値がnilで、リセット用のトークンが期限切れにならない点です(reset_password.rbの既定値)。メールが第三者に読まれた場合、そのリンクはパスワードが変更されるまで使えてしまいます。Rails 8標準ジェネレーターのリセットリンクが既定15分であることと比べても、明示的に期限を設定すべき値です。
Rails.application.config.sorcery.configure do |config|
config.user_config do |user|
user.reset_password_mailer = UserMailer
user.reset_password_expiration_period = 15.minutes.to_i
end
end
リセット依頼を受けたらuser.deliver_reset_password_instructions!、リンク先ではUser.load_from_reset_password_token(params[:token])でユーザーを引き、user.password_confirmation = params[:password_confirmation]を代入してからuser.change_password(params[:password])で更新します。前掲のUserモデルは確認用パスワードを必須にしているため、change_passwordだけを呼ぶとfalseが返り、「Password confirmation can’t be blank」で更新されません(実測)。UserMailerには既定のメソッド名reset_password_emailを定義します。メイラーを指定せずにreset_passwordを有効にすると、アプリの起動時点でArgumentError(you must define a mailer)になります。
アカウントロック(brute_force_protection)
ログインに続けて失敗するとアカウントを一時ロックします。既定は50回失敗で3600秒(1時間)のロックで(brute_force_protection.rb)、実測でも50回失敗した時点でlock_expires_atが1時間後になり、その後は正しいパスワードでもログインできませんでした。50回は総当たり対策としては緩いので、user.consecutive_login_retries_amount_limitとuser.login_lock_time_periodで回数と時間を詰めます。ロック解除メールを送るにはuser.unlock_token_mailerにメイラーを指定します。指定しなければメールは送られません。複数のアカウントに同じパスワードを試す攻撃は、アカウント単位のロックでは止まりません。Rails 7.2で入ったrate_limitをログインのcreateアクションに付け、IPアドレス単位の回数制限と組み合わせます(Rails 8標準ジェネレーターの生成コードはrate_limit to: 10, within: 3.minutes)。
user_activationによるメール認証とアカウント有効化
user_activationを入れると、登録直後のユーザーはactivation_stateがpendingになり、既定(prevent_non_active_users_to_login = true)ではメールのリンクを踏むまでログインできません。user.user_activation_mailer = UserMailerを設定し、activation_needed_emailとactivation_success_emailの2メソッドを定義します。リンク先ではUser.load_from_activation_token(params[:id])で引いてactivate!を呼びます。こちらもトークンの期限(activation_token_expiration_period)は既定でnilです。
OAuthによるGoogleログインの追加設定
externalのsubmoduleは、0.18.0のソースに20種類のプロバイダ実装を持ちます(Google・GitHub・LINE・Microsoft・Slack・Discord・Facebook・Auth0など)。まず連携情報を入れるauthenticationsテーブルを作ります。
bin/rails g sorcery:install external --only-submodules
bin/rails g model Authentication --skip-migration
bin/rails db:migrate
モデルの関連付けと、初期化ファイルの設定です。authentications_classは既定でnilなので、これを書かないとコールバック時にNoMethodError: undefined method 'sorcery_adapter' for nilで止まります(Rails 8.1.4で実測)。user_configを新しく書き足すと既存のブロックを上書きしてしまうので、生成済みのブロックに1行足します。
class User < ApplicationRecord
authenticates_with_sorcery!
# 前掲のemail・passwordのバリデーションは残したまま、次の2行を追記します
has_many :authentications, dependent: :destroy
accepts_nested_attributes_for :authentications
end
class Authentication < ApplicationRecord
belongs_to :user
end
Rails.application.config.sorcery.configure do |config|
config.external_providers = [:google]
config.google.key = ENV["GOOGLE_KEY"]
config.google.secret = ENV["GOOGLE_SECRET"]
config.google.callback_url = "http://localhost:3000/oauth/callback?provider=google"
config.google.user_info_mapping = { email: "email" }
config.user_config do |user|
user.authentications_class = Authentication
end
end
コントローラでは、login_atでプロバイダの認可画面へ送り、戻ってきたらlogin_fromで既存の連携を探します。見つからなければcreate_fromでユーザーを作ります。Sorceryはlogin_atの第2引数で渡されたstateを認可URLに載せるだけで、生成もコールバック時の照合もしません。ログインCSRFを防ぐため、ランダムな値をセッションに保存して送り、戻ってきたparams[:state]と照合してから処理します。
class OauthsController < ApplicationController
skip_before_action :require_login
def oauth
session[:oauth_state] = SecureRandom.urlsafe_base64(32)
login_at(params[:provider], state: session[:oauth_state])
end
def callback
state = session.delete(:oauth_state)
unless state.present? && ActiveSupport::SecurityUtils.secure_compare(state, params[:state].to_s)
return head :forbidden
end
provider = params[:provider]
if login_from(provider)
redirect_to root_path, notice: "ログインしました"
else
user = create_from(provider)
reset_session
auto_login(user)
redirect_to root_path, notice: "登録してログインしました"
end
rescue ActiveRecord::RecordNotUnique
redirect_to login_path, alert: "このメールアドレスは登録済みです。ログイン後に連携してください"
end
end
ルーティングはget "oauth/:provider", to: "oauths#oauth"とget "oauth/callback", to: "oauths#callback"の2本を、callbackを先に書きます。create_fromはモデルのバリデーションを通さずに保存します(external.rbのsave(validate: false))。パスワード必須のバリデーションは掛かりませんが、DB側のemail一意制約は効くので、同じメールアドレスでパスワード登録済みのユーザーがいるとActiveRecord::RecordNotUniqueになります。既存ユーザーに連携を足すときは、ログイン後にadd_provider_to_userを使います。
キーとシークレットは環境変数で渡し、コールバックURLはプロバイダの管理画面に登録した値と完全に一致させます。X(旧Twitter)のプロバイダもありますが、X APIは利用プランごとに使える機能と料金が決まっているため、採用前に開発者ポータルでログインに必要な権限が使えるかを確認してください。業務システムの社内IDと連携するSSOや多要素認証まで含めて設計する場合は、認証基盤・ID管理システム開発のように認証基盤側で組む方法もあります。トークン方式との違いはJWTとセッション・OAuthの違いを参照してください。
つまずきやすいエラーと原因
| 症状 | 主な原因 |
|---|---|
| bundle installで解決できない | Ruby 3.2未満またはRails 7.1未満 |
| DEPRECATION WARNINGが出る | redirect_back_or_toを呼んでいる |
| ログイン後に/loginへ戻る | 設定trueのままredirect_back_or_to |
| 未ログインでrootへ飛ぶ | not_authenticatedを上書きしていない |
| メール更新でパスワードエラー | バリデーションに条件がない |
| 正しいパスワードで入れない | ロック中またはactivation未完了 |
| OAuthでsorcery_adapter for nil | authentications_class未設定 |
| user.の設定が効かない | user_configブロックを2つ書いている |
| OAuthでRecordNotUnique | 同じemailの既存ユーザー |
原因が分からないときは、bin/rails consoleでUser.last.crypted_passwordが$2a$で始まるbcryptのハッシュになっているか、failed_logins_countやlock_expires_atに値が残っていないかを見ると切り分けが早くなります。セッションの保存先や失効の考え方はセッション管理とは?で扱っています。
よくある質問
Sorceryとは何のgemですか?
Ruby on Railsにログイン・ログアウト・パスワードのハッシュ化などの認証機能を組み込む軽量なgemです。画面やコントローラは生成せず、開発者が自分で書きます。英単語のsorcery(魔術)やゲームブックとは関係ありません。
Sorceryの最新バージョンと対応Rails・Rubyは?
最新は2025年12月6日公開の0.18.0です。Ruby 3.2以上・Rails 7.1以上が必要で、Rails 8.0・8.1でも動きます。この記事のコードはRails 8.1.4とRuby 4.0.6で確認しました。
SorceryとDeviseはどちらを選ぶべきですか?
登録・ロック・メール確認まで画面ごと揃えたいならDevise、画面は自作して認証の部品だけ借りたいならSorceryです。要件がログインとパスワードリセットだけの新規Rails 8アプリなら、DeviseやSorceryを追加せず、bcryptを使う標準の認証ジェネレーターで対応できます。
not_authenticatedメソッドは何をしますか?
require_loginが未ログインを検知したときに呼ばれるメソッドで、既定ではroot_pathへリダイレクトします。ApplicationControllerで上書きし、ログイン画面へ誘導するのが一般的です。
redirect_back_or_toで警告が出るのはなぜですか?
Rails 7.0で同名のメソッドがRails本体に入り、Sorceryのredirect_back_or_toがそれを上書きしているためです。config.use_redirect_back_or_to_by_rails = trueを設定し、呼び出しをredirect_to_before_login_pathに置き換えると警告が消え、ログイン前に開いたページへ戻る動きも保てます。