Laravel 6.x API認証

イントロダクション

アプリケーションの各ユーザーに結びつけたランダムトークンを利用し、API認証を行うシンプルな手法をデフォルトとしてLaravelは採用しています。config/auth.php設定ファイルの中で、apiガードはtokenドライバを定義し、使用しています。このドライバーは、受信したリクエストのAPIトークンを調べ、データベース上のユーザーに結びつけたトークンと一致するか検証することに責任を持っています。

Note: Laravelでは、シンプルなトークンベースの認証ガードを提供していますが、API認証を提供する堅牢なプロダクションアプリケーションでは、Laravel Passportの使用を考慮することを強く推奨します。

設定

データベースの準備

tokenドライバを使用する前に、usersテーブルへapi_tokenカラムを追加するマイグレーションを作成する必要があります。

Schema::table('users', function ($table) {
    $table->string('api_token', 80)->after('password')
                        ->unique()
                        ->nullable()
                        ->default(null);
});

マイグレーションできたら、migrate Artisanコマンドを実行します。

Tip!! 他のカラム名を使う場合は、config/auth.php設定ファイル中のstorage_key設定オプションを必ず更新してください。

トークン生成

usersテーブルへapi_tokenカラムを追加したら、アプリケーションに登録している各ユーザーへ、ランダムなAPIトークンを割り付ける準備が整いました。ユーザーの登録でUserモデル生成時に、トークンを割り付けるべきでしょう。laravel/ui Composerパッケージが提供する認証スカフォールドを使用する場合は、RegisterControllerのcreateメソッドで行っています。

use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Str;

/**
 * 登録バリデーション後に、新ユーザーインスタンスの生成
 *
 * @param  array  $data
 * @return \App\User
 */
protected function create(array $data)
{
    return User::forceCreate([
        'name' => $data['name'],
        'email' => $data['email'],
        'password' => Hash::make($data['password']),
        'api_token' => Str::random(80),
    ]);
}

トークンのハッシュ

前記の例では、APIトークンはデータベースへ平文のまま保存されます。SHA-256を使用し、APIトークンをハッシュしたい場合は、apiガードのhashオプションをtrueに設定してください。apiガードはconfig/auth.php設定ファイルで定義されています。

'api' => [
    'driver' => 'token',
    'provider' => 'users',
    'hash' => true,
],

ハッシュ済みトークンの生成

ハッシュ済みAPIトークンを使用する場合、ユーザー登録時にAPIトークンを生成してはいけません。代わりに、アプリケーション中にAPIトークン管理ページを実装する必要があります。このページでユーザーにAPIトークンの初期化と再生成を提供します。あるユーザーがトークンの初期化や再生成をリクエストしたら、トークンのハッシュ済みコピーをデータベースへ保存し、ビューやフロントエンドクライアントで一度だけ表示するために、平文のコピーを返す必要があります。

たとえば、指定したユーザーのトークンを初期化／再生成し、JSONレスポンスとして平文トークンを返すコントローラメソッドは、次のようになるでしょう。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Str;

class ApiTokenController extends Controller
{
    /**
     * 認証済みのユーザーのAPIトークンを更新する
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function update(Request $request)
    {
        $token = Str::random(80);

        $request->user()->forceFill([
            'api_token' => hash('sha256', $token),
        ])->save();

        return ['token' => $token];
    }
}

Tip!! 上記例のAPIトークンは、十分なエントロピーを持ちますので、「レインボーテーブル」を作成してハッシュ済みトークンのオリジナル値を探し出すのは、非現実的になります。そのため、bcryptなどの遅いハッシュ方法は必要ありません。

ルートの保護

Laravelは、受信したリクエストのAPIトークンを自動的にバリデートする、認証ガードを提供しています。アクセストークンの有効性が必要なルートへ、auth:apiミドルウェアを指定するだけです。

use Illuminate\Http\Request;

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

リクエストへのトークン付加

アプリケーションへAPIトークンを渡す方法はいくつかあります。Guzzle HTTPライブラリを使用したときの利用方法をデモンストレーションするために、いくつかのアプローチを検討してみます。アプリケーションの必要に合わせて選択してください。

クエリ文字列

アプリケーションのAPI利用側が、api_tokenクエリ文字列の値としてトークンを指定できます。

$response = $client->request('GET', '/api/user?api_token='.$token);

ペイロードのリクエスト

アプリケーションのAPI利用側が、リクエストフォームのapi_tokenパラメータへ、APIトークンを含められます。

$response = $client->request('POST', '/api/user', [
    'headers' => [
        'Accept' => 'application/json',
    ],
    'form_params' => [
        'api_token' => $token,
    ],
]);

Bearerトークン

アプリケーションのAPI利用側が、リクエストのAuthorizationヘッダへBearerトークンとして、APIトークンを提供できます。

$response = $client->request('POST', '/api/user', [
    'headers' => [
        'Authorization' => 'Bearer '.$token,
        'Accept' => 'application/json',
    ],
]);