認証、API、共有アクセス

管理API、公開共有、Webhook、WebSocketのアクセス境界を説明します。

保護されたAPIは、ローカルSessionまたは明示的に有効化したプロキシ認証から解決されるprincipalと必要な権限を要求します。workspaceの読み取りはworkspace:read、変更はworkspace:write、データソース設定・Settings・管理診断はadmin:manageが必要です。例外はhealth check、tokenでscopeされた共有route、Secretで認証するWebhookです。個々のrequest/responseは生成Server APIを参照してください。

初期認証

外部へbindする新規Serverは、管理者Secretなしでは起動しません。SHUMOKU_BOOTSTRAP_ADMIN_PASSWORD_FILEでownerだけが読めるファイルを渡す方法を推奨します。ブラウザからの初期設定を許可するSHUMOKU_ALLOW_WEB_SETUPはloopback開発専用です。

DEMO_MODEはサンプルデータを投入するだけで、匿名アクセスを許可しません。

リバースプロキシSSO

信頼境界と環境変数はインストール手順を参照してください。有効な間はローカルのログイン・初期設定・パスワード変更を無効化し、Cookieと開発用Bearerによるアクセスも許可しません。初回起動の管理者Secretは引き続き必要です。

GET /api/auth/statusはauthMethod: proxyとproxy:を付けたsubjectを返します。ロールヘッダー未設定時は既定でviewer、設定時は空・未対応のグループを拒否します。複数グループでは明示的に対応付けた最大のロールを採用します。保護APIで身元・グループが拒否されると401、認証済みでも必要な権限がない場合は403を返します。

ログアウトは組織の認証基盤で行います。Shumokuのlogout endpointが削除するのはローカルSessionだけです。非常用のローカルログインでは接続元を制限し、プロキシ認証を無効にして再起動します。authMethodをenumで検証するクライアントは、有効化前にproxyへ対応してください。

開発時のAPI操作

bun run dev:serverはloopback限定の一時credentialを生成します。credentialを表示・転記せず、専用wrapperを使います。

bun run dev:server:request -- GET /api/topologies

この経路はdevelopmentかつloopbackでのみ有効です。本番環境ではローカルSessionまたはプロキシ認証を利用します。プロキシ認証中は開発用Bearerを無視します。

共有リンクとWebhook

TopologyまたはDashboardの共有tokenは、対象resourceに限定した読み取り権限です。tokenを持つ利用者は、他の管理resourceを列挙できません。不要になった共有tokenは設定画面で失効させます。

WebhookはX-Webhook-Secret headerを推奨し、query parameterはSecretがaccess logへ残る可能性を考慮してください。

WebSocket

/wsはローカルSessionまたは信頼済みプロキシの身元、許可されたOrigin、workspace:read権限を要求します。プロキシ認証中はHTTPと同じ身元解決を使い、ローカルCookieを無視します。認可は接続時に行い、接続済みsocketは切断までprincipalを保持します。proxy配下ではWebSocket upgradeを転送してください。HTTP API外のmessage contractはServer sourceを基準とし、将来専用referenceへ抽出します。