はじめに

Laravel Sanctumは、シングルページアプリケーション（SPA）、モバイルアプリケーション、シンプルなAPIのための軽量な認証システムです。

トークンベースの認証を提供し、APIへの安全なアクセスを可能にします。Sanctumはシンプルさと使いやすさが特徴であり、複雑な認証システムを必要としないプロジェクトに最適です。

本記事では、Sanctumを用いてBasic認証とBearer認証を共存させる方法を解説します。

Basic認証は、シンプルな認証方法として知られており、ユーザー名とパスワードを直接送信することで認証を行います。一方、Bearer認証は、トークンを用いた認証方式であり、よりセキュアなAPIアクセスを実現します。

これらの認証方式には、それぞれメリット・デメリットが存在し、使い分けることでシステムのセキュリティと利便性を向上させることができます。例えば、Basic認証は実装が容易ですが、セキュリティ面ではBearer認証に劣ります。Bearer認証は、トークンを用いることでセキュリティを高めることができますが、トークンの管理が必要となります。

状況によっては、Basic認証とBearer認証を共存させる必要が生じます。例えば、開発環境ではBasic認証を用い、本番環境ではBearer認証を用いるといったケースです。本記事では、Sanctumを用いてこれらの認証方式を共存させる方法、そして実装時に発生しやすい問題とその解決策について詳しく解説します。

Sanctumとは？そのメリット・デメリット

Laravel Sanctumは、シングルページアプリケーション（SPA）、モバイルアプリケーション、シンプルなAPIのための軽量な認証システムです。 APIトークンベースの認証システムであり、ユーザーがログインするとトークンが発行され、そのトークンを使ってAPIにアクセスできるようになります。

Basic認証とBearer認証の使い分け、共存させる必要性

Basic認証とBearer認証は、それぞれ異なる特性を持つため、使い分けが必要です。Basic認証は、シンプルで実装が容易ですが、セキュリティ面ではBearer認証に劣ります。一方、Bearer認証は、トークンベースでより安全な認証方式ですが、実装が複雑になる場合があります。

これらの認証方式を共存させる必要性は、例えば以下のようなケースが考えられます。

• すでにBearer認証を使用しているシステムを、Basic認証がかかっている開発環境に設置する場合。

• セキュリティ要件の異なる複数のシステムを統合する場合。

このようなケースでは、それぞれの認証方式のメリットを活かしつつ、デメリットを補うために、Basic認証とBearer認証を共存させる構成が有効です。

Sanctumの基本設定

Sanctumを使うための基本設定について解説します。Sanctumは、LaravelアプリケーションでSPA（Single Page Application）やモバイルアプリケーション、シンプルなAPIを認証するための軽量な認証システムです。

SanctumのインストールはComposerを使って行います。

composer require laravel/sanctum

インストールが完了したら、Sanctumの設定ファイルを公開します。

php artisan vendor:publish --provider="LaravelSanctumSanctumServiceProvider"

このコマンドを実行することで、config/sanctum.phpファイルが作成されます。このファイルでは、Sanctumの動作をカスタマイズするための様々な設定オプションが用意されています。 特に重要なのはstatefulの項目で、ここにSPAのURLを記載します。これにより、指定されたドメインからのリクエストは認証状態を保持するようになります。

APIトークンの発行は、Sanctum::personalAccessToken()メソッドを使って行います。 createTokenメソッドを呼び出すことで、指定した名前のトークンを生成できます。

これらの設定を行うことで、Sanctumの基本的なセットアップが完了します。

Sanctumのインストールと設定

Sanctumは、LaravelアプリケーションにシンプルなAPI認証を提供するための公式パッケージです。SPA（Single Page Application）やモバイルアプリケーション、シンプルなトークンベースのAPIに最適です。まずは、Composerを使用してSanctumをインストールします。

composer require laravel/sanctum

インストールが完了したら、Sanctumの設定ファイルを公開します。

php artisan vendor:publish --provider="LaravelSanctumSanctumServiceProvider"

これにより、config/sanctum.phpファイルが作成されます。通常、デフォルト設定で問題ありませんが、必要に応じてstatefulガードの設定やAPIトークンの有効期限などを変更できます。

データベースマイグレーションを実行して、Sanctumに必要なテーブルを作成します。

php artisan migrate

SPA認証を使用する場合は、app/Http/Kernel.phpファイルのapiミドルウェアグループにLaravelSanctumHttpMiddlewareEnsureFrontendRequestsAreStateful::classミドルウェアを追加します。

'api' => [
    // ... other middleware
    LaravelSanctumHttpMiddlewareEnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    IlluminateRoutingMiddlewareSubstituteBindings::class,
],

statefulガードに保護されたルートへのリクエストは、Sanctumが発行したAPIトークンを使って認証されます。

SPA認証の設定

Sanctumは、SPA（Single Page Application）の認証も簡単に実装できます。SPAはフロントエンドとバックエンドが分離されているため、APIトークンを用いた認証が一般的です。Sanctumでは、このAPIトークンを発行・管理する機能を提供しています。

SanctumでSPA認証を設定するには、まずconfig/sanctum.phpファイルのstateful配列に、SPAのドメインを追加します。例えば、SPAのURLがhttp://spa.example.comの場合は、以下のように設定します。

'stateful' => [
    'spa.example.com',
],

この設定により、指定されたドメインからのリクエストは、Cookieに保存されたセッションIDを使用して認証されます。つまり、SPAからAPIリクエストを送信する際に、AuthorizationヘッダにBearerトークンを付与する必要はありません。Sanctumが自動的にCookieからセッションIDを読み取り、認証を行います。

また、CORS（Cross-Origin Resource Sharing）の設定も必要です。config/cors.phpファイルのpaths配列に、APIのパスを追加します。例えば、APIのパスが/api/*の場合は、以下のように設定します。

'paths' => ['api/*'],

この設定により、指定されたパスへのリクエストに対して、CORSヘッダが付与されます。これにより、SPAからAPIにアクセスできるようになります。

APIトークンの発行

Sanctumでは、APIトークンを発行することで、SPA(Single Page Application)やモバイルアプリケーションなどから安全にAPIにアクセスできます。トークンは、ユーザーごとに発行され、特定の有効期限を持つことができます。

Laravel SanctumでAPIトークンを発行するには、主に2つの方法があります。

1. createTokenメソッドを使う方法

   createTokenメソッドは、UserモデルにSanctumが追加するメソッドです。
   このメソッドを呼び出すことで、指定した名前のトークンを発行できます。
   例えば、webという名前のトークンを発行するには、以下のように記述します。

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

   plainTextTokenプロパティにアクセスすることで、プレーンテキスト形式のトークンを取得できます。このトークンをクライアントに返却し、クライアントはAuthorizationヘッダーにBearer {token}の形式で設定してAPIリクエストを送信します。

2. personal-access-tokensテーブルを直接操作する方法

   createTokenメソッドの内部では、personal-access-tokensテーブルにトークン情報が保存されます。
   このテーブルを直接操作してトークンを発行することも可能です。
   ただし、通常はcreateTokenメソッドを使用する方が簡単で安全です。

Basic認証の実装

SanctumでBasic認証を実装する場合、ミドルウェアauth:sanctumはそのままではBearer認証を想定しているため、工夫が必要です。Basic認証を特定のルートに適用するには、auth.basicミドルウェアを使用します。

auth:sanctumミドルウェアは、APIルートでBearerトークンによる認証を期待します。そのため、Basic認証をSanctumと共存させる場合、適用範囲を適切に制御する必要があります。

Basic認証を使用したいルートのroutes/api.phpに、以下のようにauth.basicミドルウェアを適用します。

Route::middleware('auth.basic')->group(function () {
    Route::get('/basic-auth-route', function (Request $request) {
        // Basic認証が必要な処理
        return $request->user();
    });
});

この設定により、/basic-auth-routeへのアクセスにはBasic認証が要求されます。auth.basicミドルウェアは、HTTPリクエストヘッダーのAuthorizationフィールドからBasic認証の資格情報を取得し、ユーザーを認証します。

ミドルウェア`auth:sanctum`の挙動とBasic認証

Sanctumは、デフォルトではAPIトークンによるBearer認証を想定しています。しかし、auth:sanctumミドルウェアは、Basic認証にも対応しています。auth:sanctumミドルウェアが有効なルートにアクセスがあった場合、Sanctumは以下の手順で認証を試みます。

1. Authorizationヘッダーを確認し、BearerトークンがあればBearer認証を試みます。

2. Bearerトークンがない場合、PHPの組み込み認証機能を使ってBasic認証を試みます。

3. Basic認証が成功すると、Sanctumは一時的なAPIトークンを発行し、そのトークンを使って認証を行います。このトークンはリクエストの間だけ有効で、保存はされません。

つまり、auth:sanctumミドルウェアを適用するだけで、Bearer認証とBasic認証の両方に対応できます。

この挙動を利用することで、auth:sanctumミドルウェア一つで両方の認証方式を扱えるので、APIクライアントとブラウザからのアクセスが混在するアプリケーションで特に便利です。

特定ルートへのBasic認証適用

Basic認証を特定のルートに適用するには、ミドルウェアを活用します。routes/web.phpやroutes/api.phpで、middlewareメソッドを使って適用したいルートにBasic認証を指定します。

例えば、/admin以下のルート全てにBasic認証をかけたい場合は、以下のように記述します。

Route::prefix('admin')->middleware('auth.basic')->group(function () {
    Route::get('/dashboard', function () {
        return view('admin.dashboard');
    });

     // その他のadminルート
});

auth.basicミドルウェアは、デフォルトでnameカラムを利用して認証を行います。usersテーブル以外のテーブルを利用する場合や、別のカラムを利用したい場合は、config/auth.phpのguards配列にあるbasicの設定を変更する必要があります。例えば、adminsテーブルのemailカラムを利用したい場合は、以下のように設定します。

'guards' => [
    'basic' => [
        'driver' => 'basic',
        'provider' => 'admins', // adminsプロバイダを指定
    ],
// ...
],
'providers' => [
    'admins' => [
        'driver' => 'eloquent',
        'model' => AppModelsAdmin::class, // Adminモデルを指定
    ],
// ...
]

上記のように設定することで、auth.basicミドルウェアはadminsテーブルのemailカラムを利用して認証を行うようになります。

Bearer認証の実装(SPA)

Sanctumを利用したSPA(Single Page Application)におけるBearer認証の実装方法について解説します。SanctumはAPIトークンを発行し、このトークンを利用して認証を行います。クライアントサイド（ブラウザ）からAPIリクエストを送信する際に、AuthorizationヘッダにBearer <トークン>の形式でトークンを含めることでBearer認証が実現できます。

JavaScript(Axios)を用いたBearer認証の実装例を以下に示します。

axios.get('/api/user', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => {
  // 認証成功時の処理
  console.log(response.data);
})
.catch(error => {
  // 認証失敗時の処理
  console.error(error);
});

上記のように、リクエストヘッダーにAuthorization: Bearer <トークン>を含めることで、SanctumによるBearer認証が有効になります。トークンはログイン時に取得し、安全に保管するようにしてください。

Sanctumが発行するAPIトークンの利用方法

Sanctumでは、createTokenメソッドを用いてAPIトークンを発行します。発行されたトークンは、クライアント側で安全に保管する必要があります。

トークンは、リクエストヘッダーのAuthorizationフィールドにBearerスキームで付与してAPIリクエストを行います。

例：

Authorization: Bearer <your_api_token>

JavaScriptのAxiosライブラリを使用する場合、以下のように実装できます。

axios.get('/api/user', {
  headers: {
    'Authorization': `Bearer ${your_api_token}`
  }
});

このようにトークンを付与することで、Sanctumはpersonal_access_tokensテーブルに保存されているトークンと比較し、認証を行います。

JavaScript(Axios等)を用いたBearer認証の実装例

Axiosを使ってLaravel Sanctumで保護されたAPIエンドポイントにリクエストを送信する例を以下に示します。

// Axiosのインスタンスを作成します。
const axiosInstance = axios.create({
  baseURL: '/api', // APIのベースURLを設定
  timeout: 5000, // タイムアウト時間を設定
});

// リクエストインターセプターを追加します。
axiosInstance.interceptors.request.use(
  (config) => {
    // ローカルストレージからトークンを取得します。
    const token = localStorage.getItem('sanctum_token');

    // トークンが存在する場合、AuthorizationヘッダーにBearerトークンを追加します。
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }

    return config;
  },
  (error) => {
    // エラーハンドリング
    return Promise.reject(error);
  }
);

// APIリクエストの例
axiosInstance.get('/user')
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

この例では、Axiosのインターセプターを使用して、すべてのリクエストにBearerトークンを自動的に追加しています。localStorageからトークンを取得し、AuthorizationヘッダーにBearer ${token}の形式で設定しています。リクエスト前にトークンの有無を確認することで、トークンがない場合のエラーを回避できます。

両認証の共存設定とルーティング

この章では、Basic認証とBearer認証をどのように共存させるのか、ルーティングの設定方法を含めて解説します。

Laravel Sanctumでは、ミドルウェアの適用範囲を指定することで、Basic認証とBearer認証を共存させることができます。
auth:sanctumミドルウェアをAPIルート全体に適用し、Basic認証が必要なルートにはauth.basicミドルウェアを追加で適用します。

Sanctumは、statefulガードとstatelessガードを使い分けます。SPA認証ではstatefulガードを、APIトークン認証ではstatelessガードを用います。auth:sanctumミドルウェアはデフォルトでstatefulガードを利用するため、Basic認証とSPA認証を共存させることができます。

認証方式によってルーティングを設計することで、セキュリティを向上させ、APIの利用を適切に管理できます。たとえば、管理画面へのアクセスにはBasic認証を、APIアクセスにはBearer認証を用いるといった設計が可能です。

ミドルウェアの適用範囲指定による共存設定

Sanctumを利用する場合、Basic認証とBearer認証を共存させることができます。
これは、ミドルウェアの適用範囲を適切に指定することで実現できます。
例えば、APIルートの一部をBasic認証、他の部分をBearer認証で保護することができます。

上記のように設定することで、クライアントは /api/basic 以下のAPIへアクセスする際にはBasic認証を、/api/spa 以下のAPIへアクセスする際にはBearer認証を使用する必要があります。
auth:sanctum ミドルウェアは、リクエストヘッダーに含まれる認証情報に基づいて適切な認証方式を自動的に選択します。
つまり、Basic認証とBearer認証のどちらのリクエストにも対応可能です。
これにより、APIの利用状況に応じて柔軟に認証方式を使い分けることができます。

stateful guardとstateless guard

Sanctumは、statefulな認証とstatelessな認証の両方をサポートしています。

stateful guard（セッション認証）は、従来のWebアプリケーションでよく使われる認証方式です。ユーザーがログインすると、サーバー側にセッション情報が保存され、以降のリクエストではそのセッション情報を使って認証を行います。Sanctumでは、webガードがこのstateful guardに該当します。SPA認証においては、webミドルウェアで守られたCSRFトークン発行用のエンドポイントにアクセスし、auth:sanctumミドルウェアで守られたAPIにCSRFトークンをつけてアクセスすることで認証を行います。

一方、stateless guard（トークン認証）は、APIなどでよく使われる認証方式です。クライアントは、APIトークンをリクエストヘッダーに含めてAPIにアクセスします。サーバー側は、そのトークンを検証することで認証を行います。Sanctumでは、sanctumガードがこのstateless guardに該当します。auth:sanctumミドルウェアを用いることで、リクエストヘッダーに含まれるAPIトークンを検証し、認証を行います。

Sanctumでは、webガードとsanctumガードを併用することで、WebアプリケーションとAPIの両方でシームレスな認証を実現できます。Basic認証はstatelessな認証方式であるため、Sanctumのsanctumガードと組み合わせて使用することができます。

認証方式によるルーティング設計

APIにおいてBasic認証とBearer認証を共存させる場合、ルーティング設計が重要になります。適切にルーティングを設計することで、それぞれの認証方式を必要とするエンドポイントを明確に区別し、セキュリティと利便性を両立させることができます。

たとえば、管理画面へのアクセスにはBasic認証を適用し、外部システムとの連携に用いるAPIにはBearer認証を適用するといった使い分けが可能です。

このようにルーティングを設計することで、管理画面へのアクセスはBasic認証で保護し、APIへのアクセスはBearer認証で保護することができます。
また、Basic認証とBearer認証の両方を適用したいエンドポイントも設計できます。
例えば、開発環境ではBasic認証を適用し、本番環境ではBearer認証を適用するといった切り替えも可能です。

ハマりどころと解決策

Basic認証とBearer認証を共存させる際に発生しやすい問題と、その解決策を紹介します。

Bearer認証特有のハマりどころ
Bearer認証はAuthorizationヘッダを利用するため、他の認証方式、例えばBasic認証と衝突する可能性があります。
具体的には、Basic認証が必要な環境下でBearer認証を利用する場合、認証が正常に動作しないケースがあります。
これは、Authorizationヘッダの値が両方の認証方式で競合してしまうことが原因です。

解決策

この問題を解決するためには、Bearerトークンを送信するヘッダを変更する方法があります。例えば、X-Authorizationヘッダを利用するなど、Authorizationヘッダと異なるヘッダ名を使用することで競合を回避できます。
Laravelでは、$request->bearerToken()メソッドでBearerトークンを取得しますが、このメソッドをカスタマイズすることで、X-Authorizationヘッダからもトークンを取得できるように変更できます。

カスタマイズ例

    public function bearerToken()
    {
        $header = $this->header('X-Authorization', null) ?? $this->header('Authorization', '');
        if (Str::startsWith($header, 'Bearer ')) {
            return Str::substr($header, 7);
        }
    }

上記のように、bearerToken()メソッドをオーバーライドし、X-Authorizationヘッダの値もチェックするように変更することで、Authorizationヘッダとの競合を回避できます。
ただし、このカスタマイズはvendorディレクトリ内のファイルを直接変更するのではなく、composer.jsonのfilesセクションで修正後のファイルを読み込むように設定し、exclude-from-classmapで元ファイルを無効化する必要があります。
これにより、vendorディレクトリのファイルを直接変更せずにカスタマイズを適用できます。

CORSエラーと解決策

CORS（Cross-Origin Resource Sharing）エラーは、異なるオリジン（ドメイン、プロトコル、ポートの組み合わせ）からリソースにアクセスしようとした際に発生するセキュリティエラーです。Sanctumを利用したAPIへのアクセスでこのエラーが発生した場合、ブラウザはAPIからのレスポンスをブロックします。

これらの設定後、サーバーを再起動してください。

401エラー、419エラーへの対処

API認証でよく遭遇する401 Unauthorizedエラーと419 Page Expiredエラーについて、その原因と解決策を解説します。

記載されている通り、.envファイルの設定ミスでAPIが401エラーを返すケースがあります。SANCTUM_STATEFUL_DOMAINS には www. を含めたドメインを正しく設定する必要があります。設定後、設定内容が反映されているか確認しましょう。また、セッションの期限切れも419エラーの原因となります。セッションの有効期限を適切に設定することで、この問題を回避できます。

トークンのリフレッシュ方法

Sanctumにおけるトークンのリフレッシュ方法は、SPA認証とAPIトークン認証で異なります。SPA認証では、Sanctumが自動的にトークンのリフレッシュを処理します。ユーザーがログインしている間、Sanctumはバックグラウンドで新しいトークンを発行し、古いトークンを無効化します。そのため、開発者はトークンのリフレッシュ処理を明示的に実装する必要はありません。

一方、APIトークン認証では、トークンのリフレッシュは手動で行う必要があります。APIトークンには有効期限が設定されており、期限が切れたトークンは無効になります。期限切れのトークンでAPIリクエストを送信すると、401エラーが返されます。

APIトークンをリフレッシュするには、/sanctum/csrf-cookieルートにPOSTリクエストを送信し、CSRFトークンを取得します。次に、取得したCSRFトークンをヘッダーに設定し、認証情報とともに/loginルートにPOSTリクエストを送信します。認証が成功すると、新しいAPIトークンが発行されます。

トークンのリフレッシュ処理を適切に実装することで、APIのセキュリティを維持し、ユーザーの利便性を向上させることができます。

Basic認証とBearer認証の共存設定時の注意点

Basic認証とBearer認証を共存させる場合、Authorizationヘッダの利用について注意が必要です。両方の認証方式でこのヘッダを利用するため、競合が発生する可能性があります。

上記のように、Basic認証ではBasicに続いて認証情報が、Bearer認証ではBearerに続いてトークンがAuthorizationヘッダに含まれます。

既存システムでBearer認証をAuthorizationヘッダで利用している場合、ヘッダ名を変更せずに共存させるには、サーバー側で条件分岐を行うなどの対応が必要になります。例えば、特定の環境のみ別のヘッダ(例：X-Authorization)でBearerトークンを受け付けるように変更できます。

Laravelでは、$request->bearerToken()でBearerトークンを取得しますが、この部分をカスタマイズし、Authorizationヘッダに加え、X-Authorizationヘッダからもトークンを取得できるように変更することで対応可能です。

まとめ

この記事では、Laravel Sanctumを用いてBasic認証とBearer認証を共存させる方法と、その際に発生しやすい問題点と解決策について解説しました。SanctumはシンプルなAPI認証を提供する一方で、複数の認証方式を柔軟に組み合わせることができるため、様々なシステム構成に対応できます。

SPAとAPIサーバー間の通信にはBearer認証を、特定の管理画面などにはBasic認証を適用することで、セキュリティレベルを調整しながら開発効率を高めることが可能です。

共存設定の要は、ミドルウェアauth:sanctumの適用範囲を適切に制御することです。ルーティング設定を活用して、それぞれの認証方式を適用するエンドポイントを明確に区別することで、認証に関する予期せぬ動作を防ぎ、安全なシステムを構築できます。

CORSエラーや401エラー、419エラーといったよくある問題は、設定ミスやリクエストヘッダーの不備が原因であることが多いです。エラーメッセージを注意深く確認し、適切な設定を行うことで解決できます。

Sanctumの柔軟性を活かして、安全かつ効率的なAPI認証を実現しましょう。

The post Laravel SanctumでBasic認証とBearer認証を共存させる方法とハマりどころ first appeared on 株式会社yep.