コンテンツにスキップ
Authrim

プラグイン管理

概要

プラグイン管理APIは、Authrimの機能を拡張するプラグインを管理するためのエンドポイントを提供します。通知サービス、IDプロバイダー、認証器などのプラグインを設定できます。

エンドポイント一覧

メソッドエンドポイント説明
GET/api/admin/pluginsプラグイン一覧取得
GET/api/admin/plugins/:idプラグイン詳細取得
GET/api/admin/plugins/:id/configプラグイン設定取得
PUT/api/admin/plugins/:id/configプラグイン設定更新
PUT/api/admin/plugins/:id/enableプラグイン有効化
PUT/api/admin/plugins/:id/disableプラグイン無効化
GET/api/admin/plugins/:id/healthプラグインヘルスステータス取得
GET/api/admin/plugins/:id/schemaプラグイン設定JSONスキーマ取得

プラグイン一覧取得

登録済みプラグインの一覧をステータスとともに取得します。

エンドポイント

GET /api/admin/plugins

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/plugins" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "plugins": [
    {
      "id": "notifier-console",
      "version": "1.0.0",
      "capabilities": ["notifier.email", "notifier.sms", "notifier.push"],
      "official": true,
      "meta": {
        "name": "Console Notifier",
        "description": "コンソールに通知をログ出力します。開発・テスト専用。",
        "icon": "terminal",
        "category": "notification",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/notifier/console"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "notifier-console",
      "enabled": true,
      "configSource": "default"
    },
    {
      "id": "notifier-resend",
      "version": "1.0.0",
      "capabilities": ["notifier.email"],
      "official": true,
      "meta": {
        "name": "Resend Email Notifier",
        "description": "Resend APIでトランザクションメールを送信",
        "icon": "mail",
        "category": "notification",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/notifier/resend"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "notifier-resend",
      "enabled": true,
      "configSource": "kv"
    },
    {
      "id": "authenticator-totp",
      "version": "1.0.0",
      "capabilities": ["authenticator.totp"],
      "official": true,
      "meta": {
        "name": "TOTP Authenticator",
        "description": "時刻ベースのワンタイムパスワード認証 (RFC 6238)",
        "icon": "shield-check",
        "category": "authentication",
        "stability": "stable"
      },
      "source": {
        "type": "builtin",
        "identifier": "ar-lib-plugin/builtin/authenticator/totp"
      },
      "trustLevel": "official",
      "registeredAt": 1705881600000,
      "pluginId": "authenticator-totp",
      "enabled": true,
      "configSource": "default"
    }
  ],
  "total": 3
}

プラグイン詳細取得

指定されたプラグインの詳細情報（設定とスキーマを含む）を取得します。

エンドポイント

GET /api/admin/plugins/:id

パスパラメータ

パラメータ型必須説明
idstring○プラグインID

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "plugin": {
    "id": "notifier-resend",
    "version": "1.0.0",
    "capabilities": ["notifier.email"],
    "official": true,
    "meta": {
      "name": "Resend Email Notifier",
      "description": "Resend APIでトランザクションメールを送信",
      "icon": "mail",
      "category": "notification",
      "author": {
        "name": "Authrim",
        "url": "https://authrim.com"
      },
      "license": "MIT",
      "tags": ["email", "transactional", "resend"],
      "stability": "stable",
      "documentationUrl": "https://resend.com/docs"
    },
    "source": {
      "type": "builtin",
      "identifier": "ar-lib-plugin/builtin/notifier/resend"
    },
    "trustLevel": "official",
    "registeredAt": 1705881600000
  },
  "status": {
    "pluginId": "notifier-resend",
    "enabled": true,
    "configSource": "kv",
    "lastHealthCheck": {
      "status": "healthy",
      "timestamp": 1705968000000,
      "message": "Resend APIに到達可能です"
    }
  },
  "config": {
    "apiKey": "re_l****XYZ1",
    "defaultFrom": "[email protected]",
    "replyTo": "[email protected]"
  },
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "Resend APIキー"
      },
      "defaultFrom": {
        "type": "string",
        "description": "デフォルトの送信元メールアドレス"
      },
      "replyTo": {
        "type": "string",
        "description": "返信先メールアドレス"
      }
    },
    "required": ["apiKey", "defaultFrom"]
  },
  "disclaimer": null
}

プラグイン設定取得

グローバルまたはテナント固有のプラグイン設定を取得します。

エンドポイント

GET /api/admin/plugins/:id/config

パスパラメータ

パラメータ型必須説明
idstring○プラグインID

クエリパラメータ

パラメータ型必須説明
tenant_idstring-テナント固有設定用のテナントID

リクエスト例

Terminal window
# グローバル設定
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/config" \
  -H "Authorization: Bearer {token}"


# テナント固有設定
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/config?tenant_id=tenant_123" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "pluginId": "notifier-resend",
  "tenantId": null,
  "config": {
    "apiKey": "re_l****XYZ1",
    "defaultFrom": "[email protected]"
  },
  "source": "kv"
}

プラグイン設定更新

プラグイン設定を更新します。機密フィールドは保存前に自動的に暗号化されます。

エンドポイント

PUT /api/admin/plugins/:id/config

リクエストボディ

フィールド型必須説明
configobject○プラグイン設定オブジェクト
tenant_idstring-テナント固有オーバーライド用のテナントID
secret_fieldsstring[]-暗号化するフィールドの明示的なリスト（未指定時は自動検出）

リクエスト例

Terminal window
curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/config" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "apiKey": "re_new_api_key_here",
      "defaultFrom": "[email protected]",
      "replyTo": "[email protected]"
    }
  }'

レスポンス例

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "config": {
    "apiKey": "re_n****here",
    "defaultFrom": "[email protected]",
    "replyTo": "[email protected]"
  },
  "encryptedFields": ["apiKey"]
}

プラグイン有効化

プラグインを有効化します。テナント固有の有効化にはテナントIDを指定できます。

エンドポイント

PUT /api/admin/plugins/:id/enable

リクエストボディ

フィールド型必須説明
tenant_idstring-テナント固有の有効化用テナントID

リクエスト例

Terminal window
curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/enable" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

レスポンス例

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "enabled": true
}

プラグイン無効化

プラグインを無効化します。テナント固有の無効化にはテナントIDを指定できます。

エンドポイント

PUT /api/admin/plugins/:id/disable

リクエストボディ

フィールド型必須説明
tenant_idstring-テナント固有の無効化用テナントID

リクエスト例

Terminal window
curl -X PUT "https://{tenant-domain}/api/admin/plugins/notifier-resend/disable" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{}'

レスポンス例

{
  "success": true,
  "pluginId": "notifier-resend",
  "tenantId": null,
  "enabled": false
}

プラグインヘルス取得

プラグインのヘルスステータスを取得します。

エンドポイント

GET /api/admin/plugins/:id/health

パスパラメータ

パラメータ型必須説明
idstring○プラグインID

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/plugins/notifier-resend/health" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "pluginId": "notifier-resend",
  "health": {
    "status": "healthy",
    "timestamp": 1705968000000,
    "message": "Resend APIに到達可能です"
  }
}

ヘルスステータス値

ステータス説明
healthyプラグインは正常に動作中
degradedプラグインは動作中だが問題あり
unhealthyプラグインは動作していない
unknownヘルスチェックデータなし

プラグインスキーマ取得

プラグイン設定のJSONスキーマを取得します。Admin UIでの動的フォーム生成に使用されます。

エンドポイント

GET /api/admin/plugins/:id/schema

パスパラメータ

パラメータ型必須説明
idstring○プラグインID

リクエスト例

Terminal window
curl -X GET "https://{tenant-domain}/api/admin/plugins/authenticator-totp/schema" \
  -H "Authorization: Bearer {token}"

レスポンス例

{
  "pluginId": "authenticator-totp",
  "version": "1.0.0",
  "schema": {
    "type": "object",
    "properties": {
      "issuer": {
        "type": "string",
        "default": "Authrim",
        "description": "認証アプリに表示される発行者名"
      },
      "algorithm": {
        "type": "string",
        "enum": ["sha1", "sha256", "sha512"],
        "default": "sha1",
        "description": "HMACアルゴリズム"
      },
      "digits": {
        "type": "number",
        "enum": [6, 8],
        "default": 6,
        "description": "OTPの桁数"
      },
      "period": {
        "type": "number",
        "minimum": 15,
        "maximum": 120,
        "default": 30,
        "description": "コード更新間隔（秒）"
      },
      "window": {
        "type": "number",
        "minimum": 0,
        "maximum": 5,
        "default": 1,
        "description": "時刻ずれ許容範囲（±ステップ）"
      }
    }
  },
  "meta": {
    "name": "TOTP Authenticator",
    "description": "時刻ベースのワンタイムパスワード認証 (RFC 6238)",
    "category": "authentication"
  }
}

プラグインカテゴリ

カテゴリ説明
notification通知サービス（メール、SMS、Push）
identityIDプロバイダー（Google、SAML、OIDC）
authentication認証器（TOTP、Passkey、OTP）
flowフローノード（将来の拡張）

信頼レベル

プラグインの信頼レベルは、メタデータの主張ではなく、配布元によって決定されます。

信頼レベルソース説明
officialbuiltinar-lib-pluginパッケージに含まれる
officialnpm @authrim/*公式npmスコープ
communityその他のnpm/localサードパーティプラグイン

ビルトインプラグイン

プラグインIDタイプ説明
notifier-consoleNotifierコンソールロガー（開発専用）
notifier-resendNotifierResend Email API
authenticator-totpAuthenticatorTOTP (RFC 6238)

設定の優先順位

プラグイン設定は以下の順序で解決されます：

  1. インメモリキャッシュ（60秒TTL）
  2. KVストレージ（テナント固有オーバーライド）
  3. KVストレージ（グローバル設定）
  4. 環境変数（PLUGIN_{PLUGIN_ID}_CONFIG）
  5. スキーマデフォルト値

マルチテナント設定

テナント固有のプラグイン設定はグローバル設定をオーバーライドします：

plugins:config:{pluginId}                      # グローバル
plugins:config:{pluginId}:tenant:{tenantId}    # テナントオーバーライド
plugins:enabled:{pluginId}                     # グローバル有効/無効
plugins:enabled:{pluginId}:tenant:{tenantId}   # テナント有効/無効

テナント固有の設定を管理するには、tenant_idクエリパラメータ（GET）またはリクエストボディフィールド（PUT）を使用します。

レスポンス型

PluginRegistryEntry

{
  id: string;
  version: string;
  capabilities: string[];
  official: boolean;
  meta?: {
    name: string;
    description: string;
    icon?: string;
    category: 'notification' | 'identity' | 'authentication' | 'flow';
    documentationUrl?: string;
    author?: { name: string; email?: string; url?: string };
    license?: string;
    tags?: string[];
    stability?: 'stable' | 'beta' | 'alpha' | 'deprecated';
  };
  source: {
    type: 'builtin' | 'npm' | 'local' | 'unknown';
    identifier?: string;
    npmVersion?: string;
  };
  trustLevel: 'official' | 'community';
  registeredAt: number;
}

PluginStatus

{
  pluginId: string;
  enabled: boolean;
  configSource: 'kv' | 'env' | 'default';
  loadedAt?: number;
  lastHealthCheck?: {
    status: 'healthy' | 'degraded' | 'unhealthy';
    timestamp: number;
    message?: string;
  };
}

HealthStatus

{
  status: 'healthy' | 'degraded' | 'unhealthy';
  message?: string;
  checks?: Record<string, {
    status: 'pass' | 'warn' | 'fail';
    message?: string;
  }>;
  timestamp?: number;
}