コンテンツにスキップ
Authrim

概要

@authrim/serverとは？

@authrim/serverは、リソースサーバー向けのAuthrimサーバーサイドSDKです。JWTアクセストークンの検証、DPoPプルーフの検証、JWKS鍵セットの管理、人気のあるNode.jsフレームワーク向けのミドルウェアを提供します。

アーキテクチャ

以下の図は、OAuth 2.0アーキテクチャにおける@authrim/serverの位置づけを示しています。

sequenceDiagram
    participant Client as クライアントアプリ
(@authrim/web or
@authrim/core)
    participant AuthServer as Authrim
認可サーバー
    participant Resource as リソースサーバー
(@authrim/server)

    Client->>AuthServer: 1. 認可リクエスト
    AuthServer-->>Client: 2. アクセストークン (JWT)
    Client->>Resource: 3. APIリクエスト + アクセストークン
    Resource->>AuthServer: 4. JWKS取得 (キャッシュ)
    Resource->>Resource: 5. トークン検証
    Resource-->>Client: 6. 保護されたリソース

SDKはステップ4と5を自動的に処理し、認可サーバーの公開鍵を取得・キャッシュした上で、トークンの署名とクレームを検証します。

パッケージエントリポイント

エクスポートパス目的主要エクスポート
@authrim/serverメインエントリ — クライアント、型、バリデータ、JWKS、ユーティリティAuthrimServer, ValidatedToken, BackChannelLogoutValidator
@authrim/server/providersプロバイダーインターフェースとユーティリティCryptoProvider, HttpProvider, ClockProvider, CacheProvider
@authrim/server/adapters/expressExpressミドルウェアauthrimMiddleware, authrimOptionalMiddleware
@authrim/server/adapters/fastifyFastifyフックとプラグインauthrimPreHandler, authrimPlugin, authrimOptionalPreHandler, authrimOptionalPlugin
@authrim/server/adapters/honoHonoミドルウェアauthrimMiddleware, authrimOptionalMiddleware, getAuth, getAuthTokenType
@authrim/server/adapters/koaKoaミドルウェアauthrimMiddleware, authrimOptionalMiddleware
@authrim/server/adapters/nestjsNestJSガードとユーティリティcreateAuthrimGuard, createAuthrimOptionalGuard, getAuthFromRequest, getAuthTokenTypeFromRequest

主要機能

  • JWTアクセストークン検証 — 署名検証、クレーム検証（iss、aud、exp、nbf、iat）、スコープの適用
  • DPoPプルーフ検証（RFC 9449） — JWK Thumbprintバインディングによる送信者制約トークンの検証
  • JWKS管理 — 自動ディスカバリ、Cache-Controlによるキャッシュ、鍵ローテーション対応、シングルフライトフェッチ
  • トークンイントロスペクション（RFC 7662） — 認可サーバーへの不透明トークンの状態問い合わせ
  • トークン失効（RFC 7009） — 認可サーバーでのトークン失効
  • バックチャネルログアウト（OIDC 1.0） — 認可サーバーからのログアウトトークンの検証
  • フレームワークミドルウェア — Express、Fastify、Hono、Koa、NestJS向けのすぐに使えるアダプタ
  • セキュリティ強化 — タイミングセーフ比較、alg:none拒否、SSRF対策、JWTサイズ制限

サポートされるアルゴリズム

ファミリーアルゴリズム
RSA PKCS#1 v1.5RS256, RS384, RS512
RSA-PSSPS256, PS384, PS512
ECDSAES256, ES384, ES512
EdDSAEdDSA

サポートされるランタイム

@authrim/serverは、標準的なWeb Crypto APIをサポートするあらゆるJavaScriptランタイムで動作します。

  • Node.js 18+
  • Bun
  • Deno
  • Cloudflare Workers
  • Vercel Edge Runtime

仕組み

@authrim/serverは、3つのフェーズでアクセストークンを検証します。

  1. 初期化 — 起動時に、SDKは認可サーバーのOIDCディスカバリドキュメントとJWKS（公開鍵）を取得します。これらはメモリにキャッシュされます。
  2. トークン検証 — 各リクエストに対して、SDKはJWTを解析し、kidによって正しい署名鍵を選択し、暗号署名を検証し、すべての標準クレーム（発行者、オーディエンス、有効期限など）を検証します。
  3. 継続的な鍵管理 — SDKは鍵の鮮度を監視し、Cache-Controlヘッダーを処理し、新しいkidが検出された際に自動的に鍵を再取得します（鍵ローテーション）。

これらはすべて、起動時のinit()とリクエストごとのvalidateToken()という2つのメソッド呼び出しにカプセル化されています。

AuthrimServerメソッド

メソッド説明
init()OIDCディスカバリドキュメントとJWKSを取得します。起動時に一度呼び出してください。
validateToken(token, options?)JWTアクセストークンを検証し、ValidatedTokenを返します。
validateDPoP(proof, options)DPoPプルーフJWTを検証します（RFC 9449）。
introspect(token)認可サーバーにトークンの状態を問い合わせます（RFC 7662）。
revoke(token, tokenTypeHint?)認可サーバーでトークンを失効させます（RFC 7009）。
invalidateJwksCache()次の検証時にJWKSを強制的に再取得します。

クイック例

import { AuthrimServer } from '@authrim/server';


const authrim = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});


// Initialize once at startup (fetches JWKS)
await authrim.init();


// Validate an incoming access token
const result = await authrim.validateToken(bearerToken);


console.log(result.claims.sub);    // Subject (user ID)
console.log(result.claims.scope);  // Granted scopes
console.log(result.tokenType);     // 'Bearer' or 'DPoP'
console.log(result.expiresIn);     // Seconds until expiration

フレームワークミドルウェアを使用する場合

validateToken()を手動で呼び出す代わりに、フレームワークアダプタを使用してトークンの抽出と検証を自動化できます。

import express from 'express';
import { AuthrimServer } from '@authrim/server';
import { authrimMiddleware } from '@authrim/server/adapters/express';


const app = express();
const authrim = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});
await authrim.init();


// Protected route — token validated automatically
app.get('/api/me', authrimMiddleware(authrim), (req, res) => {
  res.json({ userId: req.auth.claims.sub });
});


// Protected route with required scopes
app.delete('/api/users/:id', authrimMiddleware(authrim, { requiredScopes: ['admin:write'] }), (req, res) => {
  res.json({ deleted: true });
});


app.listen(3000);

@authrim/serverを使用すべき場面

シナリオパッケージ説明
APIでトークンを検証する@authrim/serverこのSDK — リソースサーバー向け
ブラウザ経由でユーザーをログインさせる@authrim/webブラウザベースのOAuth/OIDCフロー
SvelteKitフルスタック認証@authrim/sveltekitサーバーフック + Svelteストア
カスタムOAuthクライアントを構築する@authrim/coreプラットフォーム非依存のプロトコルライブラリ

RFC準拠

仕様RFCカバー範囲
JSON Web Token (JWT)RFC 7519トークン解析とクレーム検証
JSON Web Key (JWK)RFC 7517JWKSフェッチ、鍵インポート、鍵選択
JWK ThumbprintRFC 7638DPoP Thumbprint計算とバインディング
Token IntrospectionRFC 7662完全なイントロスペクションクライアント
Token RevocationRFC 7009完全な失効クライアント
DPoPRFC 9449ステートレスなプルーフ検証、Thumbprintバインディング
SCIMRFC 7643 / 7644エラーレスポンス形式のサポート
OIDC Core 1.0—IDトークンとクレーム検証
OIDC Back-Channel Logout 1.0—ログアウトトークン検証

次のステップ