Laravel11系でX-API-KEYを使ったAPI認証(ミドルウェアの登録からルートグループで適用）の備忘録

2025-01-22

Laravel Sanctum などによりトークンベースのSPA認証は強化されましたが、
サービス間の API リクエストでは CORS だけでは不十分 です。

そのため、X-API-KEY ヘッダを用いて API サーバ側でリクエスト元を認証する実装を行います。
ここでは Laravel 11.x 対応版 の実装方法をまとめます。

1. .env に API キーを追加

あらかじめ .env ファイルに API キーを定義します。

API_KEY=your-secret-key

2. ApiKeyMiddleware.php を作成

app/Http/Middleware に以下のようなミドルウェアを作成します。

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class ApiKeyMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        $apiKey = $request->header('x-api-key');

        if (!$apiKey || $apiKey !== env('API_KEY')) {
            return response()->json(['message' => 'Unauthorized'], 401);
        }

        return $next($request);
    }
}

3. bootstrap/app.php でミドルウェアを登録

Laravel 11 では Kernel.php ではなく bootstrap/app.php にてミドルウェアグループを定義します。

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->group('api-key', [
            \App\Http\Middleware\ApiKeyMiddleware::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })
    ->create();

4. routes/api.php にルートを追加

定義したミドルウェアグループ api-key を使用して、ルートを制限します。

Route::middleware(['api-key'])->group(function () {
    Route::get('/test', function () {
        return "hello";
    });
});

この設定により、api/test に対して x-api-key を含まないリクエストは 401 Unauthorized を返すようになります。

5. 動作確認

リクエストヘッダーに x-api-key: your-secret-key を含めた状態でアクセスします。

例（cURL）：

curl -H "x-api-key: your-secret-key" http://your-domain/api/test

注意点

  • API キーは .env に記載し、config キャッシュを忘れずに更新してください。
  • 複数のキーを許可したい場合や、キーをDBで管理したい場合は処理を拡張してください。
  • Laravel 11 では Kernel.php が廃止されているため、bootstrap/app.php による設定が必須です。

参考

以上。