tenant-pass
はじめる

05Documentation

ドキュメント

tenant-pass を組み込み、運用する方に向けた技術資料です。製品に付属する日本語のドキュメントをもとに掲載しています。HTTP API については、例やエラーの扱いを加えた API のページ もご覧ください。

状態 v0.1.0（1.0 より前） 形式 tenant-pass/v1 英語版（GitHub）

はじめに

最初に読むページです。手元で動かす手順と、全体の設計を説明します。

  1. 01

    はじめに（ローカルで試す）

    tenant-pass を手元の PostgreSQL 1 台で動かし、パスを認証情報に交換するまでの手順です。鍵とアプリトークンの作り方、テナントのロールの準備、最小の設定ファイル、curl での確認、本番に進む前に読むものをまとめています。

  2. 02

    設計

    tenant-pass を構成する部品（ゲートウェイ、アプリケーション、tenant-pass、ディレクトリ、ストア）と、それぞれが持つ鍵を紹介します。リクエストの流れ、パスワードのウィンドウ、時刻を戻さないローテーション、ストアごとの有効期限の扱い、アカウントの安全性チェックを説明します。

セキュリティ

何を守り、何を守らないか。パスの形式とパスワードの導出の正式な仕様もここにあります。

  1. 03

    脅威モデル

    tenant-pass が何を誰から守るのか、そして何を守らないのかをまとめています。守る資産、信頼の前提、乗っ取られたアプリケーションに対する効果、ゲートウェイについて残るリスク、鍵の漏洩・時計の操作・サービス妨害への考え方、はっきり対象外としていることを説明します。

  2. 04

    パスの形式（tenant-pass/v1）

    ゲートウェイが署名するパスの正式な仕様です。PASETO v4.public（Ed25519）、暗黙のアサーション、フッターの kid、クレーム、正規化済みのホスト名、時刻の決まり、検証の順序、テストベクター、Go と PHP での署名の例を説明します。

  3. 05

    パスワードの導出（tenant-pass/v1）

    ウィンドウの番号とオフセット、鍵の選び方、HMAC-SHA256 によるパスワードとソルトの計算、更新のタイミングを定めた仕様です。別に書いた Python の実装で作ったテストベクター（検証用の入力と正解の組）も載せています。

組み込む

ゲートウェイやアプリケーションに tenant-pass を組み込む方に向けた、仕様と API の説明です。

  1. 06

    tenant-pass-gateway

    すぐに使える forward-auth 方式のゲートウェイです。ID プロバイダーの JWT を検証し、ユーザーが属するテナントのパスにだけ署名します。判定の一覧、ルート、設定、Caddy・nginx・Traefik・Envoy の設定例、セッションをテナントごとに分ける方法を説明します。

  2. 07

    ゲートウェイ連携（独自のゲートウェイ）

    自前のゲートウェイやプロキシでパスに署名するときに守る決まりを説明します。すべきこととしてはいけないこと、鍵の入れ替え、実装の確かめ方、forward-auth での実装例を扱います。

  3. 08

    クライアント連携

    アプリケーションが認証情報を取得し、保持し、更新する方法を説明します。キャッシュはメモリ内だけに置くこと、refresh_at での更新、認証に失敗したときに repair を付けて 1 回だけやり直すこと、接続プールの扱い、Go での例を扱います。

  4. 09

    バックグラウンドジョブ（ジョブチケット）

    リクエストの後で動く処理に使うジョブチケットを説明します。パスとの違い、POST /v1/job-tickets による発行、スケジューラーなどの信頼された発行者、設定、チケットの形式、セキュリティ上の性質と制限を扱います。

  5. 10

    HTTP API リファレンス

    POST /v1/credentials、POST /v1/job-tickets、GET /healthz、GET /readyz のリクエストとレスポンス、エラーコード、監査ログの項目を説明します。

設定と運用

設定ファイルのすべてのキー、鍵の管理、本番での運用と監視について説明します。

  1. 11

    設定リファレンス

    設定ファイル（JSON）のすべてのキーを説明します。厳格な読み込み、シークレットはファイルで渡す決まり、tls・gateway_keys・pass・apps・directory・rotation・nodes・kms・job_tickets・limits・shutdown の各項目を扱います。

  2. 12

    鍵管理（Vault / OpenBao Transit）

    ローテーションキーと署名鍵を HashiCorp Vault / OpenBao の Transit に置き、鍵をホストからコピーできないようにする方法を説明します。得られる効果、計算結果が変わらない理由、準備の手順、ポリシー、鍵の入れ替え、可用性を扱います。

  3. 13

    運用

    本番でのデプロイの構成、最初の構築、ローテーションキーの入れ替え、ウィンドウの長さの変更、監視とアラート、侵害が疑われるときの対応、リリースされたイメージの署名の確かめ方、アップグレードを説明します。

ストア

PostgreSQL・MySQL・Redis / Valkey ごとの仕組みと、最小権限で準備する手順です。

  1. 14

    PostgreSQL

    テナントごとの PostgreSQL のロールを管理する仕組みと、必要な権限だけを与える準備の手順を説明します。SCRAM ベリファイアと VALID UNTIL、PostgreSQL 16 以降が必要な理由、安全性チェック、PgBouncer を扱います。

  2. 15

    MySQL

    テナントごとの MySQL のユーザーを、デュアルパスワードとスイーパーで管理する仕組みを説明します。管理者アカウントの権限、CREATE USER 権限の注意点、安全性チェック、レプリケーションを扱います。

  3. 16

    Redis / Valkey

    テナントごとの ACL ユーザーを、複数のパスワードとスイーパーで管理する仕組みを説明します。ACL がサーバーごとに別々であること、ACL DRYRUN による安全性チェック、キーのプレフィックスの決まりを扱います。

ドキュメントの誤りは、GitHub の Issue でお知らせください。脆弱性は Issue ではなく、非公開の報告窓口からお送りください。