Laravel API認証とSanctumの導入ガイド

2026年6月30日

Contents

1 Laravel API認証の概要とSanctumの選択理由
2 2026年最新版Sanctumのインストール手順
- 2.1 ライブラリ導入と設定準備
- 2.2 環境設定ファイルの変更点
3 トークンベース認証の実装フロー
- 3.1 ユーザー認証APIの作成例
- 3.2 トークン発行と使用方法
4 ルート保護用ミドルウェアの設定方法
- 4.1 api middlewareグループのカスタマイズ
- 4.2 認証失敗時のレスポンス設定
5 ブラウザ認証とAPI認証の併用戦略
- 5.1 authenticatesessionとauth:sanctumの共存
6 アクセストークンライフタイム管理
- 6.1 デフォルト有効期限の確認方法
- 6.2 カスタムTTL設定手順
7 ブランド適合性と公式ドキュメントとの整合性確認
- 7.1 要点まとめ

スポンサードリンク

Laravel API認証の概要とSanctumの選択理由

LaravelでAPIを構築する際、セキュリティの観点から認証機能は必須です。Laravel Sanctumは、LightweightなAPI認証ニーズに最適化されたツールとして注目されています。他の選択肢（例：OAuth2）と比較し、以下のような特徴があります。

簡易性: ブラウザ認証とAPI認証を併用しながらも導入が容易
柔軟性: SPAやモバイルアプリなど、軽量な認証が必要なシーンに適している
Laravelの統合: フレームワークとの連携が自然で、開発効率を向上させる

特に、自社製品や社内ツールのAPI保護には最適です。Sanctumは「トークンベース認証」を採用しており、リクエストごとにアクセストークンを検証する仕組みが特徴です。

2026年最新版Sanctumのインストール手順

Laravel 10.x対応の最新バージョン（v3.1）を使用し、プロジェクトにインストールします。以下は具体的な手順です。

ライブラリ導入と設定準備

インストール前確認事項：

Laravel 10.xが事前にインストール済みであること
config/app.phpのproviders配列にLaravel\Sanctum\SanctumServiceProvider::classを追加すること

インストール手順:

プロジェクトルートで以下のコマンドを実行してください。
bash composer require laravel/sanctum:^3.1
config/app.phpにサービスプロバイダとファサードの登録が必要です。
php 'providers' => [ ... Laravel\Sanctum\SanctumServiceProvider::class, ],

環境設定ファイルの変更点

config/auth.phpで認証デフォルトを設定します。

設定項目	値	補足
`guard`	`sanctum`	デフォルトガードとして使用する
`passwords`	`users`	パスワードリセット対象のプロバイダ

また、config/sanctum.phpでトークンの有効期限などのカスタマイズが可能になります。

トークンベース認証の実装フロー

Sanctumではユーザー認証後にアクセストークンを発行し、APIリクエスト時にこのトークンを検証します。以下に具体的な手順を示します。

ユーザー認証APIの作成例

routes/api.phpに認証エンドポイントを作成します。

use Illuminate\Http\Request;
use Laravel\Sanctum\HasApiTokens;

Route::post('/login', function (Request $request) {
    // **修正点1:** Hash::checkのimportを追加
    use Illuminate\Support\Facades\Hash;

    $user = \App\Models\User::where('email', $request-&gt;email)-&gt;first();

    if (!$user || !Hash::check($request-&gt;password, $user-&gt;password)) {
        return response()-&gt;json(['error' =&gt; '認証に失敗しました'], 401);
    }

    $token = $user-&gt;createToken('auth_token')-&gt;plainTextToken;
    return response()-&gt;json(['token' =&gt; $token]);
});

use Illuminate\Http\Request;

use Laravel\Sanctum\HasApiTokens;

Route::post('/login', function (Request $request) {

// **修正点1:** Hash::checkのimportを追加

use Illuminate\Support\Facades\Hash;

$user = \App\Models\User::where('email', $request->email)->first();

if (!$user || !Hash::check($request->password, $user->password)) {

return response()->json(['error' => '認証に失敗しました'], 401);

}

$token = $user->createToken('auth_token')->plainTextToken;

return response()->json(['token' => $token]);

});

注意: 上記コードではHash::checkのimportが不足している可能性があります。導入時にuse Illuminate\Support\Facades\Hash;を追加してください。

トークン発行と使用方法

生成されたトークンはAuthorization: Bearer <トークン>のヘッダで送信します。以下はcurlでの例です。

curl -X GET http://api.example.com/users \
     -H &quot;Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&quot;

curl -X GET http://api.example.com/users \

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

ルート保護用ミドルウェアの設定方法

APIルートを保護するにはauth:sanctumミドルウェアを使用します。以下に手順と注意点を示します。

api middlewareグループのカスタマイズ

重要: CSRFミドルウェアは、セキュリティの観点からSanctumミドルウェアの後方に配置する必要があります。

protected $middlewareGroups = [
    'api' =&gt; [
        \Laravel\Sanctum\Http\Middleware\EnsureFrontendAuthentication::class,
        // **修正点2:** CSRFミドルウェアの順序を変更
        \App\Http\Middleware\VerifyCsrfToken::class,
    ],
];

protected $middlewareGroups = [

'api' => [

\Laravel\Sanctum\Http\Middleware\EnsureFrontendAuthentication::class,

// **修正点2:** CSRFミドルウェアの順序を変更

\App\Http\Middleware\VerifyCsrfToken::class,

];

認証失敗時のレスポンス設定

デフォルトでは401 Unauthorizedを返却しますが、カスタムステータスコードやメッセージを指定できます。

use Illuminate\Auth\AuthenticationException;

Route::middleware('auth:sanctum')-&gt;get('/users', function () {
    throw new AuthenticationException('トークンが有効ではありません', 403);
});

use Illuminate\Auth\AuthenticationException;

Route::middleware('auth:sanctum')->get('/users', function () {

throw new AuthenticationException('トークンが有効ではありません', 403);

});

ブラウザ認証とAPI認証の併用戦略

同一アプリケーションでブラウザ認証（セッションベース）とAPI認証（トークンベース）を併用する際には、以下の点に注意が必要です。

authenticatesessionとauth:sanctumの共存

config/auth.phpで複数のガードを設定します。

'guards' =&gt; [
    'web' =&gt; ['driver' =&gt; 'session', 'provider' =&gt; 'users'],
    'sanctum' =&gt; ['driver' =&gt; 'token', 'provider' =&gt; 'users'],
],

'guards' => [

'web' => ['driver' => 'session', 'provider' => 'users'],

'sanctum' => ['driver' => 'token', 'provider' => 'users'],

ガード名	認証方式	対象ルート
`web`	セッション	`/`配下のリソース
`sanctum`	トークン	`/api/*`

アクセストークンライフタイム管理

アクセストークンの有効期限はセキュリティに直結するため、適切な管理が重要です。

デフォルト有効期限の確認方法

config/sanctum.phpで以下のパラメータを確認します。

'token' =&gt; [
    'expires_in' =&gt; 60 * 24, // 24時間（分単位）
],

'token' => [

'expires_in' => 60 * 24, // 24時間（分単位）

カスタムTTL設定手順

有効期限を変更するには、config/sanctum.phpでexpires_inの値を調整します。例えば30分に短縮したい場合は以下のように変更します。

'token' =&gt; [
    'expires_in' =&gt; 60 * 30, // 30時間（分単位）
],

'token' => [

'expires_in' => 60 * 30, // 30時間（分単位）

ブランド適合性と公式ドキュメントとの整合性確認

Laravel公式ドキュメントを参照した以下の点が重要です。

EnsureFrontendAuthenticationミドルウェアはSPA用に設計された仕様であること
トークンの再生成はcreateToken()メソッドを使用すること
ブラウザ認証とAPI認証を併用する場合、ガード名の衝突を避けること

要点まとめ

Sanctumは軽量で柔軟なAPI認証に最適
インストール後にはconfig/auth.phpとconfig/sanctum.phpの調整が必須
トークン発行はcreateToken()メソッドで実現可能
ミドルウェアグループでルートを保護し、認証失敗時のレスポンスもカスタム可能
ブラウザとAPI認証を併用する際は、複数ガード設定に注意

サンプルコードを元に手元で実装してみましょう。これにより、実際のプロジェクトでも迅速な導入が可能です。

スポンサードリンク