設定リファレンス

概要

AuthrimServerConfig オブジェクトは、トークン検証、JWKSフェッチ、DPoPサポート、プロバイダー実装を設定します。このページでは、すべての設定フィールド、プロバイダーシステム、ランタイム固有の注意点について説明します。

AuthrimServerConfigリファレンス

必須フィールド

フィールド	型	説明
issuer	string | string[]	期待されるトークンのissuer（issクレーム）。認可サーバーのissuer URLと一致する必要があります
audience	string | string[]	期待されるトークンのaudience（audクレーム）。リソースサーバーの識別子

オプションフィールド

フィールド	型	デフォルト	説明
algorithms	string[]	['RS256']	受け入れるJWT署名アルゴリズム
jwksUri	string	{issuer}/.well-known/jwks.json	JWKSエンドポイントURL。未設定の場合、issuerから自動導出
jwksCacheTtlMs	number	600000（10分）	JWKSキャッシュのTTL（ミリ秒）
clockToleranceSeconds	number	60	exp/nbf/iatチェックのクロックスキュー許容値
requiredClaims	string[]	[]	トークンに必須のクレーム
dpop	DPoPConfig | false	false	DPoP検証の設定
introspection	IntrospectionConfig	undefined	トークンイントロスペクションエンドポイントの設定
revocation	RevocationConfig	undefined	トークン失効エンドポイントの設定
http	HttpProvider	fetchHttpProvider()	ネットワークリクエスト用のHTTPプロバイダー
crypto	CryptoProvider	webCryptoProvider()	暗号化操作プロバイダー
clock	ClockProvider	systemClock()	時刻ベースのチェック用クロックプロバイダー
cache	CacheProvider	memoryCache()	JWKSおよび関連データのキャッシュプロバイダー

最小構成

最もシンプルなセットアップでは issuer と audience のみが必要です：

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

const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

これはすべてのデフォルト値を使用します：RS256アルゴリズム、自動検出されるJWKS URI、インメモリキャッシュ、Web Crypto API。

完全な設定例

import { createAuthrimServer } from '@authrim/server';
import {
  fetchHttpProvider,
  webCryptoProvider,
  systemClock,
  memoryCache,
} from '@authrim/server';

const server = createAuthrimServer({
  // Required
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',

  // JWT validation
  algorithms: ['RS256', 'ES256'],
  clockToleranceSeconds: 30,
  requiredClaims: ['sub', 'email'],

  // JWKS
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  jwksCacheTtlMs: 600000, // 10 minutes

  // DPoP
  dpop: {
    required: false,
    allowedAlgorithms: ['ES256'],
    maxIatAgeSeconds: 300,
  },

  // Token introspection
  introspection: {
    endpoint: 'https://auth.example.com/oauth/introspect',
    clientId: 'resource-server',
    clientSecret: process.env.CLIENT_SECRET,
  },

  // Token revocation
  revocation: {
    endpoint: 'https://auth.example.com/oauth/revoke',
    clientId: 'resource-server',
    clientSecret: process.env.CLIENT_SECRET,
  },

  // Providers
  http: fetchHttpProvider({ timeoutMs: 5000 }),
  crypto: webCryptoProvider(),
  clock: systemClock(),
  cache: memoryCache({ maxSize: 1000 }),
});

プロバイダーシステム

SDKはプロバイダー抽象化を使用して、コアロジックをプラットフォーム固有の実装から分離します。各プロバイダーには、ほとんどのランタイムで動作するデフォルト実装があります。

HttpProvider

すべてのHTTPリクエスト（JWKSフェッチ、イントロスペクション、失効）を処理します：

interface HttpProvider {
  fetch(url: string, init?: RequestInit): Promise<Response>;
}

デフォルト: fetchHttpProvider() — グローバルの fetch APIを使用。

カスタムHTTPプロバイダー

カスタムヘッダー、ロギング、プロキシサポートを追加します：

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

// With timeout
const http = fetchHttpProvider({ timeoutMs: 5000 });

// Fully custom
const customHttp: HttpProvider = {
  async fetch(url, init) {
    console.log(`HTTP ${init?.method ?? 'GET'} ${url}`);

    const response = await fetch(url, {
      ...init,
      headers: {
        ...init?.headers,
        'X-Custom-Header': 'value',
      },
    });

    console.log(`Response: ${response.status}`);
    return response;
  },
};

const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  http: customHttp,
});

CryptoProvider

JWT署名の検証と暗号化操作を処理します：

interface CryptoProvider {
  verifySignature(
    algorithm: string,
    key: CryptoKey,
    signature: Uint8Array,
    data: Uint8Array,
  ): Promise<boolean>;

  importJwk(
    jwk: JsonWebKey,
    algorithm: string,
  ): Promise<CryptoKey>;

  sha256(data: Uint8Array): Promise<Uint8Array>;

  calculateThumbprint(jwk: JsonWebKey): Promise<string>;
}

デフォルト: webCryptoProvider() — Web Crypto API（crypto.subtle）を使用。

CryptoProviderをカスタマイズする場合

デフォルトの webCryptoProvider() はNode.js 18以降、Bun、Deno、Cloudflare Workersで動作します。カスタム実装が必要なのは以下の場合のみです：

• Web Crypto APIをサポートしていないプラットフォームで実行する場合
• 検証にハードウェアセキュリティモジュール（HSM）を使用する必要がある場合
• すべての暗号化操作を監査またはログに記録する必要がある場合

ClockProvider

トークンの有効期限と有効性チェックのための現在時刻を提供します：

interface ClockProvider {
  nowMs(): number;
  nowSeconds(): number;
}

デフォルト: systemClock() — Date.now() を使用。

テスト用クロックの例

ユニットテスト用に制御可能なクロックを使用します：

function testClock(initialMs: number = Date.now()): ClockProvider & {
  advance(ms: number): void;
  set(ms: number): void;
} {
  let currentMs = initialMs;

  return {
    nowMs: () => currentMs,
    nowSeconds: () => Math.floor(currentMs / 1000),
    advance(ms: number) {
      currentMs += ms;
    },
    set(ms: number) {
      currentMs = ms;
    },
  };
}

// In tests
const clock = testClock();
const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  clock,
});

// Simulate time passing
clock.advance(3600 * 1000); // Advance 1 hour

CacheProvider

JWKSドキュメントおよびその他のキャッシュデータを保存します：

interface CacheProvider<T = unknown> {
  get(key: string): Promise<T | undefined>;
  set(key: string, value: T, ttlMs: number): Promise<void>;
  delete(key: string): Promise<void>;
}

デフォルト: memoryCache() — プロセス内メモリキャッシュ。

Redisキャッシュの例

マルチインスタンスデプロイメントでは、Redisなどの共有キャッシュを使用します：

import { createClient } from 'redis';
import type { CacheProvider } from '@authrim/server';

function redisCache(redisClient: ReturnType<typeof createClient>): CacheProvider {
  return {
    async get(key) {
      const value = await redisClient.get(`authrim:${key}`);
      return value ? JSON.parse(value) : undefined;
    },
    async set(key, value, ttlMs) {
      await redisClient.set(
        `authrim:${key}`,
        JSON.stringify(value),
        { PX: ttlMs },
      );
    },
    async delete(key) {
      await redisClient.del(`authrim:${key}`);
    },
  };
}

// Usage
const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  cache: redisCache(redis),
});

ランタイム固有の注意点

Node.js 18以降

すべての機能が完全にサポートされています。デフォルトプロバイダーは fetch（Node 18以降で利用可能）と crypto.subtle（Web Crypto API）を使用します。

// No special configuration needed
const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

Bun

すべての機能が完全にサポートされています。BunはWeb Crypto APIと fetch をネイティブに実装しています。

// No special configuration needed
const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

Deno

すべての機能がサポートされています。パッケージにはインポートマップが必要な場合があります：

deno.json

{
  "imports": {
    "@authrim/server": "npm:@authrim/server"
  }
}

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

const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

Cloudflare Workers

Cloudflare WorkersはWeb Crypto APIと fetch をサポートしています。最適な体験にはHonoアダプターを使用してください。

メモリキャッシュのライフサイクル

Cloudflare Workersでは、各リクエストが分離されたコンテキストで実行されます。デフォルトの memoryCache() はリクエストごとであり、JWKSキャッシュはリクエスト間で永続化されません。本番デプロイメントでは、Cloudflare KVやDurable Objectsをキャッシュプロバイダーとして使用することを検討してください。

import { Hono } from 'hono';
import { createAuthrimServer } from '@authrim/server';
import { authrimMiddleware, getAuth } from '@authrim/server/adapters/hono';

type Bindings = {
  AUTHRIM_ISSUER: string;
  AUTHRIM_AUDIENCE: string;
};

const app = new Hono<{ Bindings: Bindings }>();

app.use('/api/*', async (c, next) => {
  const server = createAuthrimServer({
    issuer: c.env.AUTHRIM_ISSUER,
    audience: c.env.AUTHRIM_AUDIENCE,
  });
  return authrimMiddleware(server)(c, next);
});

export default app;

Vercel Edge Functions

Cloudflare Workersと同様の制約があります。Web Crypto APIと fetch は利用可能ですが、メモリキャッシュは呼び出しごとに初期化されます。

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

const server = createAuthrimServer({
  issuer: process.env.AUTHRIM_ISSUER!,
  audience: process.env.AUTHRIM_AUDIENCE!,
  jwksCacheTtlMs: 300000, // 5 minutes — shorter TTL for edge
});

createAuthrimServer() vs new AuthrimServer()

SDKはサーバーインスタンスを作成する2つの方法を提供します：

createAuthrimServer()（推奨）

デフォルト値を適用し、設定を検証するファクトリ関数です：

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

const server = createAuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
});

• 作成時に必須フィールドを検証
• デフォルトプロバイダーを自動的に適用
• 完全に設定された AuthrimServer インスタンスを返す
• 無効な設定に対して configuration_error をスロー

new AuthrimServer()

高度なユースケース向けの直接コンストラクタです：

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

const server = new AuthrimServer({
  issuer: 'https://auth.example.com',
  audience: 'https://api.example.com',
  // Must provide all required fields — no defaults applied
});

createAuthrimServer()の使用を推奨

デフォルトの解決をバイパスする特別な理由がない限り、createAuthrimServer() を使用してください。ファクトリ関数はプロバイダーのデフォルト値、設定の検証、将来の新しい必須フィールドへの対応を処理します。

次のステップ

• エラーハンドリング — エラーコードとレスポンスユーティリティ
• Express & Fastifyアダプター — フレームワーク統合
• Hono、Koa & NestJSアダプター — その他のフレームワークアダプター
• SCIM 2.0クライアント — ユーザーとグループのプロビジョニング
• バックチャネルログアウト — サーバーサイドのログアウト処理