RBAC と JWT 検証で Laravel API を保護する

このガイドでは、Logto が発行するロールベースのアクセス制御 (RBAC) と JSON Web Token (JWT) を使用して、Laravel API に認可 (Authorization) を実装しセキュリティを強化する方法を説明します。

始める前に

クライアントアプリケーションは Logto からアクセストークン (Access token) を取得する必要があります。まだクライアント統合を設定していない場合は、React、Vue、Angular などのクライアントフレームワーク向けクイックスタートや、サーバー間アクセス用のマシン間通信 (M2M) ガイドをご覧ください。

このガイドは、Laravel アプリケーションにおけるこれらのトークンの サーバーサイド検証 に焦点を当てています。

A figure showing the focus of this guide

学べること

JWT 検証：アクセストークン (Access token) を検証し、認証 (Authentication) 情報を抽出する方法
ミドルウェア実装：API 保護のための再利用可能なミドルウェアの作成
権限モデル：さまざまな認可 (Authorization) パターンの理解と実装
- アプリケーション全体のエンドポイント向けグローバル API リソース
- テナント固有の機能制御のための組織 (Organization) 権限
- マルチテナントデータアクセスのための組織レベル API リソース
RBAC 統合：API エンドポイントでロールベースの権限 (Permission) とスコープ (Scope) を強制する方法

前提条件

PHP の最新安定版がインストールされていること
Laravel および Web API 開発の基礎知識
Logto アプリケーションが設定済み（必要に応じてクイックスタートを参照）

権限モデルの概要

保護を実装する前に、アプリケーションアーキテクチャに適した権限モデルを選択してください。これは Logto の 3 つの主要な認可 (Authorization) シナリオに対応しています：

グローバル API リソース
組織（非 API）権限
組織レベル API リソース

ユースケース: アプリケーション全体で共有される API リソースを保護する（組織固有ではない）
トークンタイプ: グローバルオーディエンスを持つアクセストークン
例: パブリック API、コアプロダクトサービス、管理エンドポイント
最適: すべての顧客が利用する API を持つ SaaS プロダクト、テナント分離のないマイクロサービス
詳細: グローバル API リソースの保護

💡 進める前にモデルを選択してください — このガイド全体で選択したアプローチを参照します。

クイック準備手順

Logto リソースと権限の設定

グローバル API リソース
組織（非 API）権限
組織レベル API リソース

API リソースの作成： コンソール → API リソースにアクセスし、API を登録します（例： https://api.yourapp.com）
権限の定義： read:products や write:orders などのスコープを追加します – 権限付き API リソースの定義を参照
グローバルロールの作成： コンソール → ロールにアクセスし、API 権限を含むロールを作成します – グローバルロールの設定を参照
ロールの割り当て： API アクセスが必要なユーザーまたは M2M アプリケーションにロールを割り当てます

組織権限の定義： 組織テンプレートで invite:member や manage:billing などの非 API 組織権限を作成します
組織ロールの設定： 組織テンプレートで組織固有のロールを設定し、それらに権限を割り当てます
組織ロールの割り当て： 各組織コンテキスト内でユーザーに組織ロールを割り当てます

API リソースの作成： 上記と同様に API リソースを登録しますが、組織コンテキストで使用します
権限の定義： 組織コンテキストにスコープされた read:data や write:settings などのスコープを追加します
組織テンプレートの設定： API リソース権限を含む組織ロールを設定します
組織ロールの割り当て： API 権限を含む組織ロールにユーザーまたは M2M アプリケーションを割り当てます
マルチテナント設定： API が組織スコープのデータとバリデーションを処理できることを確認します

RBAC が初めてですか？:

ロールベースのアクセス制御ガイドからステップバイステップのセットアップ手順を始めましょう。

クライアントアプリケーションの更新

クライアントで適切なスコープをリクエストする：

ユーザー認証 (Authentication)：アプリの更新 → で API スコープや組織コンテキストをリクエスト
マシン間通信： M2M スコープの設定 → でサーバー間アクセスを設定

通常、クライアント設定を次のいずれか、または複数を含めるように更新します：

OAuth フローでの scope パラメーター
API リソースアクセス用の resource パラメーター
組織コンテキスト用の organization_id

コーディング前に:

テストするユーザーまたは M2M アプリが、API に必要な権限を含む適切なロールまたは組織ロールに割り当てられていることを確認してください。

API プロジェクトの初期化

新しい Laravel プロジェクトを初期化するには、Laravel インストーラーまたは Composer を使用できます。

Laravel インストーラーを使用する場合（推奨）：

composer global require laravel/installer
laravel new your-api-name
cd your-api-name

または、Composer を直接使用する場合：

composer create-project laravel/laravel your-api-name
cd your-api-name

開発サーバーを起動します：

php artisan serve

これで基本的な Laravel プロジェクト構成が作成されます。API 開発の場合、Web 固有のミドルウェアやルートを削除したい場合があります：

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) {
        // 必要に応じて API ミドルウェアを設定
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

注記:

コントローラー、ミドルウェア、その他の機能のセットアップ方法については、Laravel ドキュメントを参照してください。

定数とユーティリティの初期化

トークンの抽出と検証を処理するために、コード内で必要な定数やユーティリティを定義してください。有効なリクエストには、Authorization ヘッダーが Bearer <アクセストークン (Access token)> の形式で含まれている必要があります。

AuthConstants.php
<?php

class AuthConstants
{
    public const JWKS_URI = 'https://your-tenant.logto.app/oidc/jwks';
    public const ISSUER = 'https://your-tenant.logto.app/oidc';
}

AuthInfo.php
<?php

class AuthInfo
{
    public function __construct(
        public readonly string $sub,
        public readonly ?string $clientId = null,
        public readonly ?string $organizationId = null,
        public readonly array $scopes = [],
        public readonly array $audience = []
    ) {}

    public function toArray(): array
    {
        return [
            'sub' => $this->sub,
            'client_id' => $this->clientId,
            'organization_id' => $this->organizationId,
            'scopes' => $this->scopes,
            'audience' => $this->audience,
        ];
    }
}

AuthorizationException.php
<?php

class AuthorizationException extends Exception
{
    public function __construct(
        string $message,
        public readonly int $statusCode = 403
    ) {
        parent::__construct($message);
    }
}

AuthHelpers.php
<?php

trait AuthHelpers
{
    protected function extractBearerToken(array $headers): string
    {
        $authorization = $headers['authorization'][0] ?? $headers['Authorization'][0] ?? null;

        if (!$authorization) {
            throw new AuthorizationException('Authorization ヘッダーがありません (Authorization header is missing)', 401);
        }

        if (!str_starts_with($authorization, 'Bearer ')) {
            throw new AuthorizationException('Authorization ヘッダーは "Bearer " で始まる必要があります (Authorization header must start with "Bearer ")', 401);
        }

        return substr($authorization, 7); // 'Bearer ' プレフィックスを削除
    }
}

Logto テナント情報の取得

Logto が発行したトークンを検証するには、次の値が必要です：

JSON Web Key Set (JWKS) URI：JWT 署名を検証するために使用される Logto の公開鍵の URL。
発行者 (Issuer)：期待される発行者値（Logto の OIDC URL）。

まず、Logto テナントのエンドポイントを見つけます。これはさまざまな場所で確認できます：

Logto コンソールの設定 → ドメイン で確認できます。
Logto で設定した任意のアプリケーション設定内の設定 → エンドポイント & 資格情報 で確認できます。

OpenID Connect ディスカバリーエンドポイントから取得する

これらの値は、Logto の OpenID Connect ディスカバリーエンドポイントから取得できます：

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

以下はレスポンス例です（他のフィールドは省略しています）：

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

コード内にハードコーディングする（推奨されません）

Logto では JWKS URI や発行者 (Issuer) のカスタマイズができないため、これらの値をコード内にハードコーディングすることも可能です。ただし、将来的に設定が変更された場合のメンテナンス負荷が増加する可能性があるため、本番アプリケーションでは推奨されません。

JWKS URI：https://<your-logto-endpoint>/oidc/jwks
発行者 (Issuer)：https://<your-logto-endpoint>/oidc

トークンと権限の検証

トークンを抽出し OIDC 設定を取得した後、次の点を検証してください：

署名：JWT は有効であり、Logto（JWKS 経由）によって署名されている必要があります。
発行者 (Issuer)：Logto テナントの発行者 (Issuer) と一致している必要があります。
オーディエンス (Audience)：Logto に登録された API のリソースインジケーター、または該当する場合は組織コンテキストと一致している必要があります。
有効期限：トークンが有効期限切れでないこと。
権限 (スコープ) (Permissions (scopes))：トークンに API / アクションに必要なスコープが含まれている必要があります。スコープは scope クレーム内のスペース区切り文字列です。
組織コンテキスト：組織レベルの API リソースを保護する場合、organization_id クレームを検証してください。

JWT の構造やクレームについて詳しくは JSON Web Token を参照してください。

各権限モデルで確認すべきこと

クレームや検証ルールは権限モデルによって異なります：

グローバル API リソース
組織（非 API）権限
組織レベル API リソース

オーディエンスクレーム (aud): API リソースインジケーター
組織クレーム (organization_id): なし
チェックするスコープ（権限） (scope): API リソース権限

オーディエンスクレーム (aud): urn:logto:organization:<id>（組織コンテキストが aud クレームに含まれる）
組織クレーム (organization_id): なし
チェックするスコープ（権限） (scope): 組織権限

オーディエンスクレーム (aud): API リソースインジケーター
組織クレーム (organization_id): 組織 ID（リクエストと一致する必要あり）
チェックするスコープ（権限） (scope): API リソース権限

非 API 組織権限の場合、組織コンテキストは aud クレーム（例：urn:logto:organization:abc123）で表されます。organization_id クレームは組織レベル API リソーストークンにのみ存在します。

ヒント:

セキュアなマルチテナント API のため、必ず権限（スコープ）とコンテキスト（オーディエンス、組織）の両方を検証してください。

検証ロジックの追加

firebase/php-jwt を使用して JWT の検証を行います。Composer を使ってインストールしてください：

composer require firebase/php-jwt

まず、JWT 検証を処理するための共通ユーティリティを追加します：

JwtValidator.php
<?php

use Firebase\JWT\JWT;
use Firebase\JWT\JWK;
use Firebase\JWT\Key;

class JwtValidator
{
    use AuthHelpers;

    private static ?array $jwks = null;

    public static function fetchJwks(): array
    {
        if (self::$jwks === null) {
            $jwksData = file_get_contents(AuthConstants::JWKS_URI);
            if ($jwksData === false) {
                throw new AuthorizationException('Failed to fetch JWKS', 401);
            }

            self::$jwks = json_decode($jwksData, true);
        }

        return self::$jwks;
    }

    public static function validateJwt(string $token): array
    {
        try {
            $jwks = self::fetchJwks();
            $keys = JWK::parseKeySet($jwks);

            $decoded = JWT::decode($token, $keys);
            $payload = (array) $decoded;

            // 発行者 (Issuer) の検証
            if (($payload['iss'] ?? '') !== AuthConstants::ISSUER) {
                throw new AuthorizationException('Invalid issuer', 401);
            }

            self::verifyPayload($payload);
            return $payload;

        } catch (AuthorizationException $e) {
            throw $e;
        } catch (Exception $e) {
            throw new AuthorizationException('Invalid token: ' . $e->getMessage(), 401);
        }
    }

    public static function createAuthInfo(array $payload): AuthInfo
    {
        $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];
        $audience = $payload['aud'] ?? [];

        if (is_string($audience)) {
            $audience = [$audience];
        }

        return new AuthInfo(
            sub: $payload['sub'],
            clientId: $payload['client_id'] ?? null,
            organizationId: $payload['organization_id'] ?? null,
            scopes: $scopes,
            audience: $audience
        );
    }

    private static function verifyPayload(array $payload): void
    {
        // 権限モデルに基づく検証ロジックをここに実装してください
        // この内容は下記の権限モデルセクションで説明します
    }
}

次に、アクセストークンを検証するミドルウェアを実装します：

app/Http/Middleware/VerifyAccessToken.php
<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class VerifyAccessToken
{
    use AuthHelpers;

    public function handle(Request $request, Closure $next): Response
    {
        try {
            $token = $this->extractBearerToken($request->headers->all());
            $payload = JwtValidator::validateJwt($token);

            // 認証情報をリクエスト属性に保存し、汎用的に利用できるようにする
            $request->attributes->set('auth', JwtValidator::createAuthInfo($payload));

            return $next($request);

        } catch (AuthorizationException $e) {
            return response()->json(['error' => $e->getMessage()], $e->statusCode);
        }
    }
}

ミドルウェアを app/Http/Kernel.php に登録します：

app/Http/Kernel.php
protected $middlewareAliases = [
    // ... 他のミドルウェア
    'auth.token' => \App\Http\Middleware\VerifyAccessToken::class,
];

権限モデルに応じて、JwtValidator 内で適切な検証ロジックを実装してください：

グローバル API リソース
組織 (非 API) 権限
組織レベル API リソース

JwtValidator.php
private static function verifyPayload(array $payload): void
{
    // オーディエンス (Audience) クレームが API リソースインジケーターと一致するか確認
    $audiences = $payload['aud'] ?? [];
    if (is_string($audiences)) {
        $audiences = [$audiences];
    }

    if (!in_array('https://your-api-resource-indicator', $audiences)) {
        throw new AuthorizationException('Invalid audience');
    }

    // グローバル API リソースに必要なスコープ (Scope) を確認
    $requiredScopes = ['api:read', 'api:write']; // 実際に必要なスコープに置き換えてください
    $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];

    foreach ($requiredScopes as $scope) {
        if (!in_array($scope, $scopes)) {
            throw new AuthorizationException('Insufficient scope');
        }
    }
}

JwtValidator.php
private static function verifyPayload(array $payload): void
{
    // オーディエンス (Audience) クレームが組織フォーマットと一致するか確認
    $audiences = $payload['aud'] ?? [];
    if (is_string($audiences)) {
        $audiences = [$audiences];
    }

    $hasOrgAudience = false;
    foreach ($audiences as $aud) {
        if (str_starts_with($aud, 'urn:logto:organization:')) {
            $hasOrgAudience = true;
            break;
        }
    }

    if (!$hasOrgAudience) {
        throw new AuthorizationException('Invalid audience for organization permissions');
    }

    // 組織 ID がコンテキストと一致するか確認（リクエストコンテキストから取得する必要があります）
    $expectedOrgId = 'your-organization-id'; // リクエストコンテキストから取得
    $expectedAud = "urn:logto:organization:{$expectedOrgId}";
    if (!in_array($expectedAud, $audiences)) {
        throw new AuthorizationException('Organization ID mismatch');
    }

    // 必要な組織スコープ (Scope) を確認
    $requiredScopes = ['invite:users', 'manage:settings']; // 実際に必要なスコープに置き換えてください
    $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];

    foreach ($requiredScopes as $scope) {
        if (!in_array($scope, $scopes)) {
            throw new AuthorizationException('Insufficient organization scope');
        }
    }
}

JwtValidator.php
private static function verifyPayload(array $payload): void
{
    // オーディエンス (Audience) クレームが API リソースインジケーターと一致するか確認
    $audiences = $payload['aud'] ?? [];
    if (is_string($audiences)) {
        $audiences = [$audiences];
    }

    if (!in_array('https://your-api-resource-indicator', $audiences)) {
        throw new AuthorizationException('Invalid audience for organization-level API resources');
    }

    // 組織 ID がコンテキストと一致するか確認（リクエストコンテキストから取得する必要があります）
    $expectedOrgId = 'your-organization-id'; // リクエストコンテキストから取得
    $orgId = $payload['organization_id'] ?? null;
    if ($expectedOrgId !== $orgId) {
        throw new AuthorizationException('Organization ID mismatch');
    }

    // 組織レベル API リソースに必要なスコープ (Scope) を確認
    $requiredScopes = ['api:read', 'api:write']; // 実際に必要なスコープに置き換えてください
    $scopes = !empty($payload['scope']) ? explode(' ', $payload['scope']) : [];

    foreach ($requiredScopes as $scope) {
        if (!in_array($scope, $scopes)) {
            throw new AuthorizationException('Insufficient organization-level API scopes');
        }
    }
}

ミドルウェアを API に適用する

これで、保護された API ルートにミドルウェアを適用します。

routes/api.php
<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::middleware('auth.token')->group(function () {
    Route::get('/api/protected', function (Request $request) {
        // リクエスト属性から認証情報へアクセス
        $auth = $request->attributes->get('auth');
        return ['auth' => $auth->toArray()];
    });
});

またはコントローラーを使用する場合：

app/Http/Controllers/Api/ProtectedController.php
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;

class ProtectedController extends Controller
{
    public function __construct()
    {
        $this->middleware('auth.token');
    }

    public function index(Request $request)
    {
        // リクエスト属性から認証情報へアクセス
        $auth = $request->attributes->get('auth');
        return ['auth' => $auth->toArray()];
    }

    public function show(Request $request)
    {
        // 保護されたエンドポイントのロジック
        $auth = $request->attributes->get('auth');
        return [
            'auth' => $auth->toArray(),
            'message' => '保護されたデータへのアクセスに成功しました'
        ];
    }
}

保護された API のテスト

アクセストークン (Access tokens) の取得

クライアントアプリケーションから: クライアント統合を設定している場合、アプリは自動的にトークンを取得できます。アクセストークン (Access token) を抽出し、API リクエストで使用してください。

curl / Postman でのテスト用:

ユーザートークン: クライアントアプリの開発者ツールを使い、localStorage またはネットワークタブからアクセストークン (Access token) をコピーします。
マシン間通信トークン: クライアントクレデンシャルフローを使用します。以下は curl を使った非公式な例です：
```
curl -X POST https://your-tenant.logto.app/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-m2m-client-id" \
  -d "client_secret=your-m2m-client-secret" \
  -d "resource=https://your-api-resource-indicator" \
  -d "scope=api:read api:write"
```
resource や scope パラメーターは API リソースや権限に応じて調整が必要です。API が組織スコープの場合は organization_id パラメーターも必要になる場合があります。

ヒント:

トークンの内容を確認したい場合は、 JWT デコーダーを使って JWT をデコード・検証できます。

保護されたエンドポイントのテスト

有効なトークンリクエスト

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

期待されるレスポンス:

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}

トークンなし

curl http://localhost:3000/api/protected

期待されるレスポンス (401):

{
  "error": "Authorization header is missing"
}

無効なトークン

curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

期待されるレスポンス (401):

{
  "error": "Invalid token"
}

権限モデルごとのテスト

グローバル API リソース
組織 (非 API) 権限
組織レベル API リソース

グローバルスコープで保護された API のテストシナリオ：

有効なスコープ: 必要な API スコープ（例: api:read, api:write）を含むトークンでテスト
スコープ不足: 必要なスコープがない場合は 403 Forbidden を期待
誤ったオーディエンス: オーディエンスが API リソースと一致しない場合は 403 Forbidden を期待

# 必要なスコープがないトークン - 403 を期待
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected

組織固有のアクセス制御のテストシナリオ：

有効な組織トークン: 正しい組織コンテキスト（組織 ID とスコープ）を含むトークンでテスト
スコープ不足: ユーザーが要求された操作の権限を持たない場合は 403 Forbidden を期待
誤った組織: オーディエンスが組織コンテキスト（urn:logto:organization:<organization_id>）と一致しない場合は 403 Forbidden を期待

# 別の組織用トークン - 403 を期待
curl -H "Authorization: Bearer token-for-different-organization" \
  http://localhost:3000/api/protected

API リソース検証と組織コンテキストを組み合わせたテストシナリオ：

有効な組織 + API スコープ: 組織コンテキストと必要な API スコープの両方を持つトークンでテスト
API スコープ不足: 組織トークンに必要な API 権限がない場合は 403 Forbidden を期待
誤った組織: 別の組織のトークンで API にアクセスした場合は 403 Forbidden を期待
誤ったオーディエンス: オーディエンスが組織レベルの API リソースと一致しない場合は 403 Forbidden を期待

# API スコープがない組織トークン - 403 を期待
curl -H "Authorization: Bearer organization-token-without-api-scopes" \
  http://localhost:3000/api/protected

さらに詳しく

実践でのロールベースのアクセス制御 (RBAC)：アプリケーションのための安全な認可 (Authorization) の実装

マルチテナント SaaS アプリケーションの構築：設計から実装までの完全ガイド

始める前に​

学べること​

前提条件​

権限モデルの概要​

クイック準備手順​

Logto リソースと権限の設定​

クライアントアプリケーションの更新​

API プロジェクトの初期化​

定数とユーティリティの初期化​

Logto テナント情報の取得​

OpenID Connect ディスカバリーエンドポイントから取得する​

コード内にハードコーディングする（推奨されません）​

トークンと権限の検証​

各権限モデルで確認すべきこと​

検証ロジックの追加​

ミドルウェアを API に適用する​

保護された API のテスト​

アクセス トークン (Access tokens) の取得​

保護されたエンドポイントのテスト​

権限モデルごとのテスト​

さらに詳しく​