Authlete Study Session 2025-08 - チケット販売サービス

このプロジェクトは Authlete 勉強会 2025-08 で使用するサンプルのチケット販売サービスです。

OAuth 2.1 認可サーバー、MCP (Model Context Protocol) サーバー、構造化ログシステムを統合した包括的な実装

🎯 プロジェクト概要

このプロジェクトは以下の3つのコンポーネントから構成される統合アプリケーションです：

1. チケット販売Webアプリケーション - Express.js + Passport.js
2. OAuth 2.1 認可サーバー - Authlete 3.0 をバックエンドとして利用
3. MCP サーバー - OAuth 保護されたチケット操作API

✨ 主要機能

🔐 OAuth 2.1 認可サーバー

• OAuth 2.1 準拠: 認可コードフロー、PKCE必須 (RFC 7636)
• OAuth 拡張機能: Server Metadata (RFC 8414)、Dynamic Client Registration (RFC 7591/7592)
• Authlete統合: Authlete 3.0 API をバックエンドサービスとして利用
• セキュリティ: HTTPS必須、Bearer Token認証、セッション管理

🤖 MCP (Model Context Protocol) サーバー

• OAuth保護: スコープベースアクセス制御 (mcp:tickets:read, mcp:tickets:write)
• チケット操作: リスト取得、検索、予約、キャンセル、履歴取得
• HTTP統合: Streamable HTTP によるMCPプロトコル対応
• 動的制御: 環境変数による OAuth 有効/無効切り替え

📊 構造化ログシステム

• 複数レベル: ERROR, WARN, INFO, DEBUG, TRACE
• 環境変数制御: LOG_LEVEL と TEST_LOG_LEVEL による動的設定
• 専用ロガー: OAuth, MCP, Authlete コンポーネント別
• 構造化出力: JSON形式のコンテキスト情報付きログ

🚀 クイックスタート

1. Authlete セットアップ

まず、Authlete でサービスとクライアントを設定します。

Claude Code ユーザー向け（推奨）

Claude Code を使用している場合、自動セットアップコマンドが利用できます：

/authlete-setup

このコマンドを実行すると：

• Authlete サービス・クライアントの自動作成
• 環境変数テンプレートの生成（.env.template）
• 詳細なセットアップ手順の表示

コマンド実行後は、Authleteコンソールからサービスアクセストークンを取得して.envファイルに設定するだけで完了です。

前提条件: Authlete MCP サーバーのインストールが必要です。

Authlete MCP サーバーの Claude Code への追加

Claude Code で Authlete MCP サーバーを使用するには、以下のようにプロジェクトまたはグローバルに MCP サーバーを追加します。

プロジェクトローカルに追加:

claude mcp add authlete --scope local -- docker run --rm -i \
  -e ORGANIZATION_ACCESS_TOKEN=YOUR_ORGANIZATION_ACCESS_TOKEN \
  -e ORGANIZATION_ID=YOUR_ORGANIZATION_ID \
  -e AUTHLETE_API_URL=https://jp.authlete.com \
  -e AUTHLETE_API_SERVER_ID=53285 \
  -e LOG_LEVEL=INFO \
  ghcr.io/watahani/authlete-mcp:latest

グローバルに追加:

claude mcp add authlete --scope global -- docker run --rm -i \
  -e ORGANIZATION_ACCESS_TOKEN=YOUR_ORGANIZATION_ACCESS_TOKEN \
  -e ORGANIZATION_ID=YOUR_ORGANIZATION_ID \
  -e AUTHLETE_API_URL=https://jp.authlete.com \
  -e AUTHLETE_API_SERVER_ID=53285 \
  -e LOG_LEVEL=INFO \
  ghcr.io/watahani/authlete-mcp:latest

環境変数の取得方法:

• ORGANIZATION_ACCESS_TOKEN、ORGANIZATION_ID、AUTHLETE_API_SERVER_ID の取得方法は Authlete Terraform ドキュメント を参照してください
• 日本リージョンの場合 AUTHLETE_API_URL は https://jp.authlete.com を AUTHLETE_API_SERVER_ID は 53285 を使用します

手動セットアップ（Claude Code なしの場合）

Claude Code を使用していない場合は、jq と curl を使用して手動でサービスとクライアントを作成できます。

📋 詳細な手順: docs/manual-setup.md

概要:

1. Authlete Terraform ドキュメントから認証情報を取得
2. examples/ の設定ファイルを使用してサービス作成
3. OAuth クライアント（Confidential/Public）を作成
4. 環境変数ファイル（.env）を自動生成

2. 環境準備

# 依存関係のインストール
npm install

# SSL証明書の生成（初回のみ）
npm run generate-ssl

# 環境変数の設定（Authlete セットアップ完了後）
# .env ファイルに AUTHLETE_SERVICE_ACCESS_TOKEN を設定

3. アプリケーションの起動

# HTTPS + OAuth + MCP 統合モード（推奨）
npm run dev

# デバッグログ有効化
LOG_LEVEL=debug npm run dev

4. MCP Introspector での動作確認

アプリケーション起動後、MCP Introspector を使用して動作確認できます：

# 自己署名証明書を認識してMCP Introspectorを起動
NODE_EXTRA_CA_CERTS="$PWD/ssl/localhost.crt" \
npx @modelcontextprotocol/inspector https://localhost:3443/mcp

5. アクセス

• Webアプリケーション: https://localhost:3443
• MCP サーバー: https://localhost:3443/mcp
• OAuth認可エンドポイント: https://localhost:3443/oauth/authorize
• ヘルスチェック: https://localhost:3443/health

📋 システムアーキテクチャ

以下は、MCP Client、Authorization Server、MCP Server、Authleteを含む完全なOAuth 2.1通信フローを示したシーケンス図です：

sequenceDiagram
    participant U as User
    participant C as MCP Client
    participant AS as Authorization Server (AS)
    participant AL as Authlete<br/>(backend APIs)
    participant MS as MCP Server (= Resource Server)<br/>(MCP API + Protected Resources)

    %% Initial MCP Server Access (Authentication Challenge)
    rect rgb(255, 240, 240)
        Note over C,MS: Initial MCP Server Access (Authentication Challenge)
        C->>MS: POST /mcp (MCP Protocol)<br/>(without Authorization header)
        MS-->>C: 401 Unauthorized<br/>WWW-Authenticate: Bearer realm="baseUrl",<br/>error="invalid_request",<br/>error_description="Access token is required",<br/>resource_metadata="baseUrl/.well-known/oauth-protected-resource/mcp"
    end

    %% MCP Protected Resource Metadata
    rect rgb(240, 255, 240)
        Note over C,MS: MCP Protected Resource Metadata Discovery
        C->>MS: GET /.well-known/oauth-protected-resource/mcp
        MS-->>C: 200 {authorization_servers: [baseUrl], resource: "baseUrl/mcp",<br/>scopes_supported: ["mcp:tickets:read", "mcp:tickets:write"], ...}
        
        Note over C: From MCP(PR) metadata, client learns AS base URL.<br/>Then it discovers AS metadata by two methods:<br/>1) well-known (RFC 8414)<br/>2) AS service configuration API (backed by Authlete)
    end

    %% Authorization Server Metadata Discovery
    rect rgb(240, 240, 255)
        Note over C,AL: Authorization Server Metadata Discovery
        C->>AS: GET /.well-known/oauth-authorization-server
        AS->>AL: GET /service/configuration
        AL-->>AS: 200 OAuth Server Metadata
        AS-->>C: 200 {authorization_endpoint, token_endpoint,<br/>registration_endpoint, introspection_endpoint,<br/>code_challenge_methods_supported: ["S256"], ...}
    end

    %% Dynamic Client Registration (if needed)
    rect rgb(255, 255, 240)
        Note over C,AL: Dynamic Client Registration (RFC 7591)
        C->>AS: POST /oauth/register {redirect_uris, grant_types, response_types,<br/>client_name, token_endpoint_auth_method, ...}
        AS->>AL: POST /client/registration {json: enhanced_metadata}
        AL-->>AS: 201 {action: "CREATED", responseContent}
        AS-->>C: 201 {client_id, client_secret, registration_access_token, ...}
    end

    %% Authorization (PKCE, two-step with Authlete)
    rect rgb(250, 240, 255)
        Note over U,AL: OAuth 2.1 Authorization Code + PKCE Flow
        U->>C: Start sign-in / connect MCP
        C->>C: Generate code_verifier / code_challenge=S256(...)<br/>state, nonce
        C->>AS: GET /oauth/authorize?response_type=code&<br/>client_id, redirect_uri, scope=mcp:tickets:read&state, nonce,<br/>code_challenge, code_challenge_method=S256&<br/>resource=https://localhost:3443/mcp&<br/>authorization_details=[{type:"ticket-reservation"}]

        AS->>AL: POST /auth/authorization {parameters}
        AL-->>AS: 200 {action: "INTERACTION", ticket, client, scopes,<br/>authorizationDetails, ...}

        alt User not authenticated
            AS-->>C: 302 /auth/login?return_to=/oauth/authorize/consent
            C->>AS: Login credentials (Passport.js)
            AS-->>C: 302 /oauth/authorize/consent
        end

        AS->>U: Consent UI with authorization details options<br/>(standard vs custom limits)
        U-->>AS: POST /oauth/authorize/decision<br/>{authorized: true, authorizationDetailsJson}

        AS->>AL: POST /auth/authorization/issue<br/>{ticket, subject, authorizationDetails?: {elements: [...]}}
        AL-->>AS: 200 {action: "LOCATION", responseContent}
        AS-->>C: 302 redirect_uri?code=...&state=...
    end

    %% Token Request
    rect rgb(240, 255, 255)
        Note over C,AL: Token Request
        C->>AS: POST /oauth/token<br/>grant_type=authorization_code, code,<br/>redirect_uri, code_verifier, client_id, client_secret
        AS->>AL: POST /auth/token<br/>{parameters, clientId, clientSecret}
        AL-->>AS: 200 {action: "OK", responseContent}
        AS-->>C: 200 {access_token, token_type: "Bearer",<br/>refresh_token?, expires_in, scope, ...}
    end

    %% Access MCP Resource
    rect rgb(255, 250, 240)
        Note over C,MS: MCP Protocol with OAuth Protection
        C->>MS: POST /mcp (MCP Protocol)<br/>Authorization: Bearer <access_token>
        MS->>AL: POST /auth/introspection {token, scopes: ["mcp:tickets:read"]}
        AL-->>MS: 200 {action: "OK", subject, scopes, accessTokenResources,<br/>authorizationDetails?, ...}

        Note over MS,AL: Token Validation
        MS->>MS: Verify accessTokenResources matches MCP endpoint<br/>Execute MCP tool with authorization details constraints<br/>(e.g., maxAmount limit for ticket reservations)
        MS-->>C: 200 MCP Protocol Response

        C->>U: Show results
    end

Loading

アーキテクチャの主要ポイント

OAuth 2.1 コア機能:

• 認可コードフロー: PKCE必須による安全な認証
• Bearer Token認証: RFC 6750準拠のトークンベース認証
• HTTPS必須: セキュアな通信の強制

OAuth 拡張機能:

• Server Metadata (RFC 8414): /.well-known/oauth-authorization-server
• Dynamic Client Registration (RFC 7591/7592): 動的クライアント登録
• Resource Indicators (RFC 8707): MCPリソースへのスコープ制限
• Authorization Details: 詳細権限制御（チケット予約の金額制限等）
• Protected Resource Metadata: /.well-known/oauth-protected-resource/mcp

この統合アーキテクチャにより、Claude AIなどのMCPクライアントが、セキュアなOAuth 2.1認証を通じて、チケット販売システムのリソースに安全にアクセスできます。

🔧 API エンドポイント

システム API

• GET /health - ヘルスチェック（プロトコル判定付き）

OAuth 2.1 認可サーバー API

• GET /oauth/authorize - OAuth認可エンドポイント
• POST /oauth/token - トークンエンドポイント
• POST /oauth/introspection - トークン検証エンドポイント
• GET /oauth/authorize/consent - 認可同意画面
• POST /oauth/authorize/decision - 認可決定処理
• GET /.well-known/authorization-server - OAuth Server Metadata (RFC 8414)

チケット API（認証要）

• GET /api/tickets - チケット一覧
• GET /api/tickets/:id - チケット詳細
• POST /api/tickets/:id/reserve - チケット予約
• GET /api/my-reservations - 予約履歴
• DELETE /api/reservations/:id - 予約キャンセル

認証 API

• GET /auth/login - ログインページ
• POST /auth/login - ログイン実行
• POST /auth/register - ユーザー登録
• POST /auth/logout - ログアウト
• GET /auth/profile - プロフィール取得

MCP API（OAuth保護）

• POST /mcp - MCP サーバーエンドポイント
• GET /mcp/health - MCP ヘルスチェック
• GET /mcp/info - MCP サーバー情報

🧪 テスト実行

推奨テストワークフロー

# 1. テスト用サーバーを起動（OAuth無効モード）
MCP_OAUTH_ENABLED=false NODE_ENV=test npm run dev

# 2. 別ターミナルで全テストを実行
npx playwright test --reporter=list

# 3. OAuth機能の統合テスト
npx playwright test tests/oauth-*.spec.ts

テストカテゴリ別実行

# MCP サーバーテスト（OAuth無効）
MCP_OAUTH_ENABLED=false npx playwright test tests/mcp-server.spec.ts

# OAuth 統合テスト
npx playwright test tests/oauth-token-flow.spec.ts

# HTTPS セキュリティテスト
npx playwright test tests/https-specific.spec.ts

# デバッグログ有効化でテスト
TEST_LOG_LEVEL=debug npx playwright test

期待されるテスト結果

成功カテゴリ（OAuth無効モード）:

• ✅ MCP サーバーテスト: 8/8
• ✅ HTTPS セキュリティテスト: 3/3
• ✅ OAuth メタデータテスト: 5/5
• ✅ 基本機能テスト: 2/2

OAuth関連テスト:

• OAuth有効時: 認証フローが正常動作
• OAuth無効時: テスト実行のため期待される失敗

🐛 デバッグ機能

構造化ログシステム

プロジェクトには環境変数で制御可能な構造化ログシステムが実装されています：

# デバッグログ有効化でサーバー起動
LOG_LEVEL=debug npm run dev

# 詳細なトレースログまで出力
LOG_LEVEL=trace npm run dev

# テスト実行時のログレベル制御
TEST_LOG_LEVEL=debug npx playwright test

# OAuth トークンフローのデバッグ
LOG_LEVEL=debug npx playwright test tests/oauth-token-flow.spec.ts

利用可能なログレベル:

• error: エラーのみ
• warn: 警告以上
• info: 情報以上（デフォルト）
• debug: デバッグ情報以上
• trace: すべてのログ

専用ロガーによる分類:

• oauthLogger: OAuth関連（認可・トークン・認証）
• mcpLogger: MCP関連（サーバー・ツール・接続）
• authleteLogger: Authlete API関連（リクエスト・レスポンス）

ログ出力例

# OAuth認可フローのデバッグログ例
[2025-01-15 10:30:45] [DEBUG] [OAuth] Authorization request received {
  "clientId": "mcp-public-client",
  "responseType": "code",
  "scopes": ["mcp:tickets:read", "mcp:tickets:write"]
}

[2025-01-15 10:30:46] [DEBUG] [MCP] MCP endpoint protected by OAuth {
  "requiredScopes": ["mcp:tickets:read"],
  "accessToken": "Bearer at_xxx...xxx"
}

🏗️ プロジェクト構造

src/
├── app.ts                      # 統合アプリケーション（HTTP/HTTPS切り替え対応）
├── utils/
│   └── logger.ts              # 構造化ログシステム
├── config/
│   ├── database.ts            # MySQL データベース設定
│   └── mock-database.ts       # モックデータベース設定
├── routes/                    # Web API ルート
│   ├── auth.ts               # 認証API
│   └── tickets.ts            # チケットAPI
├── oauth/                     # OAuth 2.1 認可サーバー実装
│   ├── authlete/             # Authlete API統合
│   │   ├── client.ts         # Authlete HTTP クライアント
│   │   └── types/            # Authlete API型定義
│   ├── config/               # OAuth設定
│   │   ├── authlete-config.ts # Authlete接続設定
│   │   └── oauth-config.ts    # OAuth一般設定
│   ├── controllers/          # OAuth コントローラー
│   │   ├── authorization.ts   # 認可エンドポイント
│   │   ├── token.ts          # トークンエンドポイント
│   │   ├── introspection.ts  # トークン検証エンドポイント
│   │   └── authorization-server-metadata.ts # Server Metadata
│   ├── middleware/           # OAuth ミドルウェア
│   │   └── oauth-middleware.ts # Bearer Token認証
│   └── routes/               # OAuth ルーティング
│       └── oauth-routes.ts    # OAuth エンドポイント定義
├── mcp/                      # MCP サーバー実装
│   ├── server.ts             # スタンドアローンMCPサーバー
│   ├── http-main.ts          # HTTP MCP サーバー
│   ├── tools/                # MCP ツール実装
│   │   ├── ticket-tools.ts   # チケット操作ツール
│   │   └── types/            # ツールスキーマ定義
│   ├── data/                 # データアクセス層
│   │   └── connection-manager.ts # データベース接続管理
│   └── config/               # MCP設定
│       └── mcp-config.ts     # MCP サーバー設定
├── middleware/
│   └── auth.ts               # 認証ミドルウェア
├── services/                 # ビジネスロジック
│   ├── AuthService.ts        # 認証サービス
│   └── TicketService.ts      # チケット管理サービス
└── types/
    └── index.ts              # TypeScript型定義

public/                       # フロントエンド
├── index.html               # メイン画面
└── app.js                   # JavaScript

ssl/                         # SSL証明書（HTTPS使用時）
├── localhost.crt            # 自己署名証明書
└── localhost.key            # 秘密鍵

tests/                       # テストファイル
├── oauth-token-flow.spec.ts # OAuth トークンフローテスト
├── mcp-server.spec.ts       # MCP サーバーテスト
└── https-specific.spec.ts   # HTTPS セキュリティテスト

🔐 セキュリティ機能

HTTPS 必須環境

• 証明書管理: 自己署名証明書の生成・信頼設定
• リダイレクト: HTTP→HTTPS 301リダイレクト
• セキュリティヘッダー: HSTS, CSP, X-Frame-Options
• セキュアクッキー: secure: true, httpOnly: true

OAuth 2.1 セキュリティ

• PKCE必須: 認可コードインターセプト攻撃対策
• Bearer Token: RFC 6750 準拠のトークン認証
• スコープ制御: 細粒度アクセス制御
• セッション保護: CSRF攻撃対策
• 状態検証: OAuth state パラメータによる保護

MCP セキュリティ

• OAuth統合: アクセストークンによる認証
• スコープベース: mcp:tickets:read, mcp:tickets:write
• 動的制御: テスト時の認証バイパス機能

🔧 環境変数

.env.example をコピーして .env を作成：

cp .env.example .env

主要な環境変数

# サーバー設定
HTTPS_PORT=3443                # HTTPSポート（default: 3443）
SESSION_SECRET=your-secret     # セッション秘密鍵

# MCP設定
MCP_OAUTH_ENABLED=true         # MCP OAuth認可（default: true、NODE_ENV=testでfalse）

# ログ設定
LOG_LEVEL=info                 # サーバーログレベル（error/warn/info/debug/trace）
TEST_LOG_LEVEL=warn            # テストログレベル

# Authlete OAuth設定（HTTPS必須）
AUTHLETE_SERVICE_ACCESS_TOKEN=your-service-token  # Authlete Service Access Token
AUTHLETE_SERVICE_ID=your-service-id               # Authlete Service ID  
AUTHLETE_BASE_URL=https://jp.authlete.com         # Authlete API Base URL

📊 データベース

使用技術

• 現在: モックデータベース（メモリ内）
• データソース: プリロードされたサンプルデータ

データ構造

• users - ユーザー情報（id, username, password, email, created_at）
• tickets - チケット情報（id, title, description, price, available_seats, total_seats, event_date, created_at）
• reservations - 予約情報（id, user_id, ticket_id, seats_reserved, reservation_date, status）

サンプルデータ

• Authlete勉強会 2025-08 (¥5,000, 50席)
• Node.js ワークショップ (¥8,000, 30席)
• セキュリティ入門セミナー (¥3,000, 100席)

🔒 HTTPS 証明書設定

認可サーバーの実装では HTTPS必須 のため、Self-signed証明書を信頼する設定が必要です。

⚠️ 重要な注意事項

• 以下の設定は 開発環境のみ で実施してください
• 本番環境では正式なCA署名付き証明書を使用してください

証明書生成と信頼設定

# SSL証明書を生成
npm run generate-ssl

# macOS での信頼設定
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ssl/localhost.crt

# Linux (Ubuntu/Debian) での信頼設定
sudo cp ssl/localhost.crt /usr/local/share/ca-certificates/localhost.crt
sudo update-ca-certificates

# ブラウザでの一時的な信頼（推奨）
# 1. https://localhost:3443 にアクセス
# 2. 「詳細設定」→「localhost にアクセスする（安全ではありません）」をクリック

🎯 OAuth 2.1 認可フロー

完全な認可コードフロー

1. 認可リクエスト (GET /oauth/authorize)

   https://localhost:3443/oauth/authorize?
     response_type=code&
     client_id=mcp-public-client&
     redirect_uri=https://client.example.com/callback&
     scope=mcp:tickets:read mcp:tickets:write&
     code_challenge=CODE_CHALLENGE&
     code_challenge_method=S256&
     state=STATE_VALUE
   

2. ユーザー認証

   • 未認証ユーザーは自動的にログインページにリダイレクト
   • セッションベース認証でユーザー確認

3. 同意画面表示 (GET /oauth/authorize/consent)

   • 要求されたスコープの詳細表示
   • ユーザーの明示的な同意取得

4. 認可決定 (POST /oauth/authorize/decision)

   • 許可/拒否の処理
   • Authlete API による認可コード発行

5. トークン交換 (POST /oauth/token)

   {
     "grant_type": "authorization_code",
     "code": "AUTHORIZATION_CODE",
     "redirect_uri": "https://client.example.com/callback",
     "client_id": "mcp-public-client",
     "code_verifier": "CODE_VERIFIER"
   }

トークン検証 (POST /oauth/introspection)

{
  "token": "ACCESS_TOKEN",
  "token_type_hint": "access_token"
}

🤖 MCP (Model Context Protocol) 統合

OAuth保護されたMCPツール

ツール名	必要スコープ	説明
list_tickets	mcp:tickets:read	利用可能なチケット一覧取得
search_tickets	mcp:tickets:read	チケット検索
reserve_ticket	mcp:tickets:write	チケット予約
cancel_reservation	mcp:tickets:write	予約キャンセル
get_user_reservations	mcp:tickets:read	ユーザー予約履歴取得

MCP クライアント接続例

MCP Introspector を使用したテスト

MCP IntrospectorはOAuthのDynamic Client Registration (DCR) に対応しており、自動的にOAuth認可フローを処理します。

1. 前提条件：SSL証明書の生成

MCP IntrospectorはHTTPS接続が必要なため、まず自己署名証明書を生成します：

# SSL証明書を生成
npm run generate-ssl

この証明書生成スクリプト（scripts/generate-ssl-cert.sh）は以下を実行します：

• 2048bit RSA秘密鍵の生成
• localhost用のX.509証明書の生成
• Subject Alternative Names (SAN) の設定 (localhost, 127.0.0.1, ::1)
• 適切なファイル権限の設定

生成される証明書：

• ssl/localhost.key - 秘密鍵
• ssl/localhost.crt - 証明書
• ssl/localhost.conf - OpenSSL設定ファイル

2. サーバーの起動

HTTPS + OAuth + MCP統合モードでサーバーを起動：

# HTTPS + OAuth + MCP統合サーバー起動
npm run dev

3. MCP Introspector での接続

自己署名証明書をNode.jsが認識するよう、NODE_EXTRA_CA_CERTS環境変数で証明書を指定してIntrospectorを起動：

NODE_EXTRA_CA_CERTS="$PWD/ssl/localhost.crt" \
npx @modelcontextprotocol/inspector https://localhost:3443/mcp

4. Introspector での操作

Introspectorが起動すると：

1. 自動DCR: IntrospectorがDynamic Client Registrationを自動実行
2. OAuth認可: ブラウザでOAuth認可フローが開始される
3. ツール利用: 認証完了後、MCPツールが利用可能になる

利用可能なツール：

• list_tickets - チケット一覧取得 (スコープ: mcp:tickets:read)
• search_tickets - チケット検索 (スコープ: mcp:tickets:read)
• reserve_ticket - チケット予約 (スコープ: mcp:tickets:write)
• cancel_reservation - 予約キャンセル (スコープ: mcp:tickets:write)
• get_user_reservations - 予約履歴取得 (スコープ: mcp:tickets:read)

5. 開発・テスト時の認可バイパス

開発時は認可を無効化して簡単にテスト可能：

# OAuth無効モードでサーバー起動
MCP_OAUTH_ENABLED=false npm run dev

# 認可なしでIntrospector接続（証明書指定）
NODE_EXTRA_CA_CERTS="$PWD/ssl/localhost.crt" \
npx @modelcontextprotocol/inspector https://localhost:3443/mcp

6. 自動テストでの検証

# MCP サーバーテスト（OAuth無効）
MCP_OAUTH_ENABLED=false npx playwright test tests/mcp-server.spec.ts

# OAuth統合テスト（実際のトークンフロー）
npx playwright test tests/oauth-token-flow.spec.ts

# DCRテスト（Dynamic Client Registration）
npx playwright test tests/dcr.spec.ts

動的OAuth制御

# テスト時: OAuth認可無効
MCP_OAUTH_ENABLED=false NODE_ENV=test npm run dev

# 本番時: OAuth認可有効
MCP_OAUTH_ENABLED=true npm run dev

# デフォルト: NODE_ENV=test なら無効、それ以外は有効
npm run dev

🛠️ Claude Code スラッシュコマンド

このプロジェクトには Claude Code で利用できる専用スラッシュコマンドが用意されています。

/test-commands

包括的なテストコマンドガイド：

/test-commands

• OAuth、MCP、Ticket Service の3種類のテスト分類
• GitHub Actions 相当のテスト実行手順
• デバッグ・トラブルシューティング方法
• 環境変数設定ガイド

/authlete-setup

Authlete サービス・クライアントの自動セットアップガイド：

/authlete-setup

• MCP を利用したサービス・クライアント作成手順
• 環境変数の設定方法
• 設定値の区別（SERVICE_API_KEY vs AUTHLETE_SERVICE_ACCESS_TOKEN）
• 一括セットアップスクリプト例

使用方法: Claude Code で /authlete-setup と入力すると、詳細なセットアップ手順が表示されます。

重要: AUTHLETE_SERVICE_ACCESS_TOKEN は SERVICE_API_KEY とは異なり、Authleteコンソールから別途取得が必要です。

📊 実装完了状況

✅ 完全実装済み

1. OAuth 2.1 認可サーバー

   • ✅ 認可コードフロー（PKCE必須）
   • ✅ トークンエンドポイント
   • ✅ トークン検証（Introspection）
   • ✅ Bearer Token認証ミドルウェア

2. OAuth 拡張機能

   • ✅ Server Metadata (RFC 8414)
   • ✅ Dynamic Client Registration (RFC 7591/7592)
   • ✅ Protected Resource Metadata

3. MCP サーバー

   • ✅ チケット操作ツール（5種類）
   • ✅ OAuth統合とスコープベース制御
   • ✅ HTTP Streamable対応
   • ✅ 動的認証有効/無効切り替え

4. 構造化ログシステム

   • ✅ 複数ログレベル（5段階）
   • ✅ 環境変数による動的制御
   • ✅ 専用ロガー（OAuth/MCP/Authlete）
   • ✅ JSON構造化出力

5. 統合Webアプリケーション

   • ✅ HTTP/HTTPS動的切り替え
   • ✅ セッション管理
   • ✅ 認証・認可
   • ✅ セキュリティヘッダー

🏆 技術的成果

• OAuth 2.1準拠: 認可コードフロー、PKCE必須 (RFC 7636)、Bearer Token (RFC 6750)
• OAuth拡張機能: Server Metadata (RFC 8414)、DCR (RFC 7591/7592)、Resource Indicators (RFC 8707)
• MCP仕様準拠: Model Context Protocol 完全対応
• セキュリティ: HTTPS必須、PKCE、Bearer Token、スコープベース制御
• 開発体験: 構造化ログ、環境変数制御、包括的テストスイート
• 統合性: OAuth+MCP+Webアプリのシームレス統合

📈 テスト成功率

• 全テスト: 38/57 成功（67%）
• コア機能: MCP (8/8), HTTPS (3/3), OAuth メタデータ (5/5) - 100% 成功
• OAuth機能: 認可フロー、トークン発行・検証、認証ミドルウェア - 完全動作

🚀 次期開発への展望

スケーラビリティ向上

• マルチテナント対応
• 負荷分散とキャッシュ戦略
• データベース最適化

セキュリティ強化

• OAuth 3.0 移行準備
• 追加スコープとクレーム管理
• セキュリティ監査機能

ユーザビリティ改善

• MCP クライアント SDK 提供
• OAuth 管理ダッシュボード
• リアルタイム通知機能

📁 設定ファイルとドキュメント

Authlete 設定復元

Claude Code と Authlete MCP を使用する場合:

現在の Authlete サービス・クライアント設定を MCP で簡単に再作成できるサンプルファイルを提供しています：

• Authlete MCP セットアップガイド - Claude Code への MCP 追加と設定復元手順
• サービス設定サンプル - OAuth 2.1 サービス設定のJSONテンプレート
• クライアント設定サンプル - Confidential/Public クライアント設定のJSONテンプレート

Claude Code と Authlete MCP を使用しない場合:

examples/ フォルダのサンプル設定を参考に、Authlete コンソールから手動でサービスとクライアントを作成する必要があります：

1. Authlete Console でサービス作成
2. OAuth 2.1 設定（PKCE必須、認可コードフロー有効）
3. クライアント作成（パブリッククライアントとコンフィデンシャルクライアント）
4. 適切なスコープとリダイレクトURIの設定

---

📝 開発者向け注意事項

• デモサービスのためセキュリティは最小限の実装
• 決済処理はモック実装
• 本格運用時は適切なエラーハンドリングとバリデーションを追加
• Authlete の本番環境では適切な認証情報管理が必要

このプロジェクトは OAuth 2.1、MCP、構造化ログシステムを統合した包括的なサンプル実装として、認証・認可の学習と実践に最適な環境を提供します。