方針
- loopback 以外の bind ではトークンを必須とし、起動時に検証します(未設定なら
SettingsErrorで起動を拒否)。 - トークンは
Authorization: Bearerと WebSocket のSec-WebSocket-Protocol: bearer.*を受け付けます。URL クエリの?token=は既定で拒否します(OSUI_ALLOW_QUERY_TOKEN=trueで明示的に許可した場合のみ。URL はアクセスログ・ブラウザ履歴・Referer に残るため非推奨)。 - mTLS と OIDC は gateway の要件に合わせて個別に有効化します。非 loopback gateway では TLS 必須です。
- 静的アセット(HTML / CSS / JS)はトークンなしで配信されます。機密情報は含まれません。
- Colab からの公開トンネル接続はデフォルトで無効(Colab の利用ポリシーに抵触するため)。
- demo backend で起動した場合は UI 上部に常時「DEMO MODE」バナーを表示し、実データと区別できます。
認証方式
OSUI_AUTH_TOKEN を設定すると、すべての /api/* と WebSocket ハンドシェイクが保護されます。クライアントからトークンを渡す方法は次の 3 つです。
| 方式 | 用途 | 既定 |
|---|---|---|
Authorization: Bearer <token> | REST / SSE。CLI・スクリプト・通常の fetch から利用 | 有効 |
Sec-WebSocket-Protocol: bearer.<token> | WebSocket。ブラウザは WS に独自ヘッダを付けられないため、同梱 UI もこの方式を使用 | 有効 |
?token=<token>(クエリ) | ヘッダを付けられない旧来のクライアント向けの互換手段 | 無効(OSUI_ALLOW_QUERY_TOKEN=true で有効化) |
なぜクエリトークンを既定で無効にしているか
URL に含めたトークンは、リバースプロキシのアクセスログ、ブラウザの履歴やオートコンプリート、
他サイトへ遷移する際の
Referer ヘッダなど、保護されない場所に残ります。
同梱 UI は subprotocol 方式に移行済みのため、通常はクエリ方式を有効にする必要はありません。
リモート gateway への接続(mTLS / OIDC)
- クライアント証明書を使う場合は
OSUI_GATEWAY_CERTとOSUI_GATEWAY_KEYを同時に指定します(片方だけの指定は起動時に拒否)。CA 検証はOSUI_GATEWAY_CA_CERTで行います。 - OIDC クライアント認証は
OSUI_OIDC_ISSUER・OSUI_OIDC_CLIENT_ID・OSUI_OIDC_CLIENT_SECRET・OSUI_OIDC_AUDIENCEで設定します。OSUI_OIDC_CLIENT_SECRETはOSUI_OIDC_ISSUERを、OSUI_OIDC_ISSUERはOSUI_OIDC_CLIENT_IDを要求します。
公開前チェックリスト
| 項目 | 確認方法 | |
|---|---|---|
| 1 | トークンを設定した | OSUI_AUTH_TOKEN に十分長いランダム値を設定 |
| 2 | 公開 bind を理解している | OSUI_HOST を loopback 以外にする場合、トークン未設定では起動しないことを確認 |
| 3 | ?token= を有効にしていない | OSUI_ALLOW_QUERY_TOKEN が未設定(false)であること |
| 4 | gateway への接続が TLS | 非 loopback gateway へは mTLS / OIDC / TLS を使用 |
| 5 | demo のまま公開していない | 実 gateway に接続できない環境で公開する場合、demo backend である旨を利用者へ明示(UI の DEMO MODE バナー) |
| 6 | 信頼境界を確認した | リバースプロキシ・トンネル越しにアクセスログへトークンが残らない構成か |
既知の制約と免責
- 本プロジェクトは OpenShell 本体(Apache License 2.0)の非公式 UI レイヤーであり、NVIDIA の製品ではありません。
- データの漏えい・改ざん・消失について、いかなる保証も行いません。重要な環境では gateway 側の policy とネットワーク境界を併せて設定してください。
- WebSocket ハンドシェイクで
Sec-WebSocket-Protocolに複数の値が並ぶ場合、トークンの位置によっては echo する subprotocol がずれる可能性があります(DEV-MEMO.md に記録)。 - エラーコードと対処は リファレンスの「エラーと対処」 を参照してください。