メインコンテンツにスキップ
バージョン: 0.2.0-beta.1

クラス: MCPAuth

mcp-auth ライブラリのメインクラスです。保護されたリソースのための認証 (Authentication) ポリシーを作成するためのファクトリーおよびレジストリとして機能します。

サーバー構成で初期化され、トークンベースの認証 (Authentication) 用の Express ミドルウェアを生成する bearerAuth メソッドを提供します。

例​

resource server モードでの利用例​

新しいアプリケーションにはこの方法が推奨されます。

import express from 'express';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const app = express();

const resourceIdentifier = 'https://api.example.com/notes';
const authServerConfig = await fetchServerConfig('https://auth.logto.io/oidc', { type: 'oidc' });

const mcpAuth = new MCPAuth({
  // `protectedResources` は単一の構成オブジェクトまたはその配列を指定できます。
  protectedResources: [
    {
      metadata: {
        resource: resourceIdentifier,
        authorizationServers: [authServerConfig],
        scopesSupported: ['read:notes', 'write:notes'],
      },
    },
  ],
});

// 保護されたリソースメタデータを処理するルーターをマウント
app.use(mcpAuth.protectedResourceMetadataRouter());

// 設定したリソース用の API エンドポイントを保護
app.get(
  '/notes',
  mcpAuth.bearerAuth('jwt', {
    resource: resourceIdentifier, // このエンドポイントが属するリソースを指定
    audience: resourceIdentifier, // 任意で 'aud' クレームを検証
    requiredScopes: ['read:notes'],
  }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    res.json({ notes: [] });
  },
);

authorization server モードでのレガシー利用例（非推奨）​

後方互換性のためにサポートされています。

import express from 'express';
import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const app = express();
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(
    'https://auth.logto.io/oidc',
    { type: 'oidc' }
  ),
});

// レガシー認可サーバーメタデータを処理するルーターをマウント
app.use(mcpAuth.delegatedRouter());

// デフォルトポリシーでエンドポイントを保護
app.get(
  '/mcp',
  mcpAuth.bearerAuth('jwt', { requiredScopes: ['read', 'write'] }),
  (req, res) => {
    console.log('Auth info:', req.auth);
    // ここで MCP リクエストを処理
  },
);

コンストラクター​

コンストラクター​

new MCPAuth(config: MCPAuthConfig): MCPAuth;

MCPAuth のインスタンスを作成します。 エラー時にすぐ失敗するよう、全体の構成を事前に検証します。

パラメーター​

config​

MCPAuthConfig

認証 (Authentication) 構成。

戻り値​

MCPAuth

プロパティ​

config​

readonly config: MCPAuthConfig;

認証 (Authentication) 構成。

メソッド​

bearerAuth()​

呼び出しシグネチャ​

bearerAuth(verifyAccessToken: VerifyAccessTokenFunction, config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">): RequestHandler;

リクエストの Authorization ヘッダー内の アクセス トークン (Access token) を検証する Bearer 認証 (Authentication) ハンドラー（Express ミドルウェア）を作成します。

パラメーター​
verifyAccessToken​

VerifyAccessTokenFunction

アクセス トークン (Access token) を検証する関数です。文字列として アクセス トークン (Access token) を受け取り、検証結果に解決される promise（または値）を返す必要があります。

参照

VerifyAccessTokenFunction で verifyAccessToken 関数の型定義を確認できます。

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken">

Bearer 認証 (Authentication) ハンドラーのためのオプション構成。

参照

BearerAuthConfig で利用可能な構成オプション（verifyAccessToken と issuer を除く）を確認できます。

戻り値​

RequestHandler

アクセス トークン (Access token) を検証し、検証結果をリクエストオブジェクト（req.auth）に追加する Express ミドルウェア関数。

参照​

handleBearerAuth で実装詳細および req.auth（AuthInfo）オブジェクトの拡張型を確認できます。

呼び出しシグネチャ​

bearerAuth(mode: "jwt", config?: Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig): RequestHandler;

事前定義された検証モードを使用して、リクエストの Authorization ヘッダー内の アクセス トークン (Access token) を検証する Bearer 認証 (Authentication) ハンドラー（Express ミドルウェア）を作成します。

'jwt' モードでは、認可サーバーの JWKS URI から JWK Set を使って JWT 検証関数を作成します。

パラメーター​
mode​

"jwt"

アクセス トークン (Access token) の検証モード。現在は 'jwt' のみサポートされています。

参照

VerifyAccessTokenMode で利用可能なモードを確認できます。

config?​

Omit<BearerAuthConfig, "issuer" | "verifyAccessToken"> & VerifyJwtConfig

JWT 検証オプションやリモート JWK Set オプションを含む、Bearer 認証 (Authentication) ハンドラーのためのオプション構成。

参照

  • VerifyJwtConfig で JWT 検証のための構成オプションを確認できます。
  • BearerAuthConfig で利用可能な構成オプション（verifyAccessToken と issuer を除く）を確認できます。
戻り値​

RequestHandler

アクセス トークン (Access token) を検証し、検証結果をリクエストオブジェクト（req.auth）に追加する Express ミドルウェア関数。

参照​

handleBearerAuth で実装詳細および req.auth（AuthInfo）オブジェクトの拡張型を確認できます。

例外​

'jwt' モード使用時にサーバーメタデータに JWKS URI が指定されていない場合にスローされます。

delegatedRouter()​

delegatedRouter(): Router;

インスタンスに提供されたメタデータで、レガシー OAuth 2.0 認可サーバーメタデータエンドポイント （/.well-known/oauth-authorization-server）を提供するための委譲ルーターを作成します。

戻り値​

Router

インスタンスに提供されたメタデータで OAuth 2.0 認可サーバーメタデータエンドポイントを提供するルーター。

非推奨​

代わりに protectedResourceMetadataRouter を使用してください。

例​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

const app = express();
const mcpAuth: MCPAuth; // 初期化済みと仮定
app.use(mcpAuth.delegatedRouter());

例外​

resource server モードで呼び出された場合にスローされます。

protectedResourceMetadataRouter()​

protectedResourceMetadataRouter(): Router;

設定されたすべてのリソースに対して OAuth 2.0 保護リソースメタデータエンドポイントを提供するルーターを作成します。

このルーターは、構成で指定された各リソース識別子に対して正しい .well-known エンドポイントを自動的に作成します。

戻り値​

Router

OAuth 2.0 保護リソースメタデータエンドポイントを提供するルーター。

例外​

authorization server モードで呼び出された場合にスローされます。

例​

import express from 'express';
import { MCPAuth } from 'mcp-auth';

// mcpAuth が 1 つ以上の `protectedResources` 構成で初期化されていると仮定
const mcpAuth: MCPAuth;
const app = express();

// 構成したリソース識別子に基づき、`/.well-known/oauth-protected-resource/...` でメタデータを提供
app.use(mcpAuth.protectedResourceMetadataRouter());