Laravel Sanctumで安全にAPIを保護する方法
はじめに
LaravelでAPIを開発するとき、Laravel Sanctum は認証に関する便利な仕組みを提供してくれます。 APIのセキュリティを高めるためには、トークン管理や複数ドメイン間の認証などをしっかり押さえておきたいところではないでしょうか。 そこで皆さんが理解しやすいよう、実務での活用シーンを交えながら話を進めていきます。 技術的な要素に慣れていない方でも、平易な言葉を通じてイメージをつかんでいただけるよう心がけます。
Laravel Sanctumとは
Laravel Sanctumは、シンプルなトークン発行とCookieベースの認証フローを同時に実現する仕組みです。 以前はLaravel Passportがよく使われていましたが、OAuth2.0ほど大掛かりな認証は不要だけれどトークン発行はしたいという場面にフィットするのが特徴です。 また、SPA（Single Page Application）と連携してCookieベースで認証できるようにするなど、多様な認証パターンに対応できる点が魅力ですね。
主な特徴
1つ目は、Cookieベースでのセッション認証が扱いやすいことです。 他ドメインからのリクエストには注意が必要ですが、適切に設定するとSPAとの連携がスムーズになります。
2つ目は、トークン発行が容易な点です。 トークンごとに権限（abilities）を設定し、用途に応じた粒度の制御を行うことができます。
3つ目は、アプリケーションのスケールに合わせやすい設計です。 セッション認証とトークン認証を場面に応じて選択できるので、小規模な開発から大規模なシステムまで柔軟に対応できます。
Cookieベース認証とトークンベース認証
Laravel Sanctumでは、大きく分けて2つの認証方法があります。 1つ目は、SPAなどで使いやすいCookieセッション認証です。 2つ目は、APIトークン認証です。
Cookieベースの認証は、従来のセッション管理を踏襲しているため、フロントエンド側でトークンを直接保持せずに済むという利点があります。 ただし、CORS（クロスオリジンリソースシェアリング）の設定や、statefulな認証を行うためのドメイン設定などが必要になります。
一方でトークンベースの認証では、発行されたトークンをフロントエンド側で保持し、リクエストごとにヘッダーにトークンを含めて送ります。 こちらは複数の外部サービスやデバイスを想定したシステムなどで役立つでしょう。 手軽にトークンを発行できる一方、トークンの管理や失効のタイミングをしっかり決める必要があります。
Laravel Sanctumの導入手順
Laravelの最新バージョンを使い始めるとき、Sanctumも比較的簡単にセットアップできます。 手順を概観してみましょう。
インストール
まずはComposerでSanctumをインストールします。
composer require laravel/sanctum
その後、マイグレーションを実行します。
php artisan migrate
これによって、APIトークンを管理するためのテーブルが作成されます。
ミドルウェアの設定
config/app.phpでSanctumのService Providerが登録されていることを確認したうえで、kernel.php にミドルウェアを追加します。
しかし、デフォルトのLaravelインストールではすでに自動設定されている場合が多いです。
状況に合わせて sanctum ミドルウェアを適宜ルートに組み込みましょう。
設定ファイルの確認
config/sanctum.php の内容を見てみると、statefulな認証をするドメインの記載欄があります。
例えば、SANCTUM_STATEFUL_DOMAINS 環境変数に認証を許可するドメインを入力しておき、Cookieベース認証で問題が起きないよう調整します。
フロントエンドを別ドメインで動かす場合などは特に注意が必要です。
SPAでの認証フロー
VueやReactなどのSPAと連携するときは、Cookieベース認証を使う場合が多いです。 一般的には、認証済みユーザーであることを示すセッションCookieを発行し、それを利用する形となります。
フローの概略
- フロントエンドから
/loginのようなエンドポイントへ認証情報を送信 - サーバー側がユーザーを認証し、Cookieをセットした状態でレスポンス
- フロントエンドはCookie自体を触らず、以降のAPIリクエストでは自動的にCookieが付与される
このとき、CORSの設定で withCredentials を許可し、かつ SANCTUM_STATEFUL_DOMAINS を正しく設定しないとCookieが送信されない可能性があります。
Cookieの送受信にはCORSやHTTPSの設定が絡むため、本番環境では安全性を意識してドメインやプロトコルを整える必要があります。
トークン認証の活用
トークン認証は、モバイルアプリや外部サービスとの連携など、Cookieが使いにくい環境で役立ちます。 特にAPIキー感覚で扱える点がわかりやすいでしょう。
トークンの発行
Laravelではユーザーモデルから簡単にトークンを発行できます。
<?php // ユーザーの認証が済んだあとなどで $token = $user->createToken('example-token', ['create-posts', 'delete-posts']); // 実際のトークン文字列が欲しい場合 $plainTextToken = $token->plainTextToken;
createToken メソッドの第2引数ではトークンの権限（abilities）を設定できます。
この権限を使って、特定のAPI操作だけを許可する細かい制御を実装することも可能です。
トークンの使用方法
APIリクエスト時に、Authorizationヘッダーへ Bearer トークン文字列 を付与します。 例として、クライアント側でのHTTPリクエストは以下のようになります。
curl -X GET \ -H "Accept: application/json" \ -H "Authorization: Bearer <発行されたトークン>" \ https://example.com/api/user
サーバー側ではSanctumのミドルウェアがBearerトークンを読み取り、該当トークンが有効かどうかを確認します。
複数アプリケーション間の認証
Laravel Sanctumを使うと、1つのLaravelバックエンドに対して複数のフロントエンドやアプリケーションから認証を行うこともあります。
Cookie認証を中心にする場合は、認証を行う各アプリケーションのドメインを SANCTUM_STATEFUL_DOMAINS へ追記する方法が一般的です。
これによって、どのドメインからのリクエストにCookieを送信してよいかを指定できます。
一方、トークン認証の場合は、どのアプリケーションからリクエストしても同じようにBearerトークンをヘッダーに載せるだけです。 ただし、トークンの管理方法については統一したルールを設けておかないと、API利用時の混乱を招くかもしれません。
実務での活用例
実際の現場では、以下のようなケースでLaravel Sanctumを使う場面があります。
- SPAフロントエンドと連携する管理画面
- 外部サービスと連携するデータ取得API
- 社内ツール向けに簡単なAPIキーを発行して、利用者を限定したいとき
たとえば、管理画面を社内利用のみとしたい場合はトークン認証でアクセス制限をかけ、外部に公開するエンドポイントはCookieベースで細かい利用制限を行うなど、組み合わせもできます。 このように実装の種類を柔軟に変えられるのがSanctumの便利なところです。
管理や運用の段階では、トークンの期限や権限を適宜見直し、不要になったトークンを取り消すなどのメンテナンスも重要です。
よくある疑問やトラブルシューティング
Laravel Sanctumを使い始めると、Cookie関連のエラーやトークンの権限設定の混乱が発生する場合があるかもしれません。 ここでは代表的な疑問点やトラブルを簡単に整理します。
Cookieが送信されない
多くの場合、CORS設定が原因となります。
特に withCredentials: true を有効にしつつ、SANCTUM_STATEFUL_DOMAINS にフロントエンドのドメインを追加することを忘れがちです。
同じドメインであれば問題になりにくいですが、サブドメインや別ドメインを跨ぐ場合は慎重に設定を調整してみてください。
トークンの権限が反映されない
トークン発行時にabilitiesを設定していても、アプリ側で正しくチェックしていないケースもあります。
APIルートでability:ミドルウェアを適切に組み合わせる、もしくは各コントローラやリクエストクラスで権限チェックを実装してみましょう。
SPAとトークン認証を混在させたい
単一のアプリケーション内でCookie認証とトークン認証を同時に扱いたい場面もあるかもしれません。
この場合は、特定のAPIルートはセッション認証（auth:sanctum）で保護し、その他のAPIはトークン認証用のルートグループを作成するなどの分け方が考えられます。
まとめ
今回は Laravel Sanctum を使った認証方法について、Cookieベースとトークンベースという2つのアプローチを中心にお話ししました。 最新バージョンのLaravelであればセットアップが容易で、SPAとの連携や複数アプリケーションを横断する認証にも活用しやすいでしょう。
Cookieベースの認証はセキュアかつシンプルな運用が可能ですが、CORSやドメイン設定を慎重に調整することが大切です。 一方、トークン認証はモバイルアプリなどと連携しやすい手軽さがあるものの、トークンの発行や失効を適切に管理する必要があります。
皆さんが開発を進めるうえで、どちらの方式がプロジェクトに合っているかを考えることが大切です。 ぜひ状況や要件に合わせて、Laravel Sanctumの機能を取り入れてみてはいかがでしょうか。