概念とテナントモデル#

この文書では、統合に必要なテナント階層、Client、Environment、ドメイン、session、MAU の関係を説明する。

テナント階層#

Workspace
└── Project
    ├── Test Environment
    │   └── Client
    └── Production Environment
        └── Client

Management API の GET /v1/environments/{environmentId} は type、status、issuer、interaction_domain、rp_id を返す。統合に必要な Canonical Issuer と Interaction Domain はこの response から取得する。GET /v1/clients?environment_id=... は client_type、token_endpoint_auth_method、redirect_uris などを返す。

Client type と token endpoint 認証#

Authorization Server は require_pkce の値にかかわらず、全 Client に PKCE S256 を要求する。

対応する grant は Authorization Code と Refresh Token である。client_credentials、machine-to-machine Client type、Implicit、Resource Owner Password Credentials は提供しない。

ID prefix#

Resource ID は prefix と暗号学的乱数からなり、連番や email address 由来ではない。ID body は 20 byte の乱数を 32 文字の base32url で表現する。

Resource ID は opaque 値として扱い、prefix 以外から内部状態を推測しない。req_ は request ID であり、resource ID ではない。

Test と Production#

Environment.type は test または production である。別 Environment には別の User pool があり、Test から Production へ User、Session、Passkey、Social connection、Client、署名鍵、Webhook secret、RP ID をコピーしない。Environment の issuer は生成後に変更しない。

Management API は Workspace、Project、Environment、Client などを管理する API である。Management API key は Bearer 認証に使い、発行時に Workspace と scope が固定される。secret は sk_live_ で始まる。これは Management API key の prefix であり、Client ID や OIDC Client secret とは異なる。Test Environment 用にも sk_live_ で発行されるため、prefix から Environment の type を推測してはならない。

Issuer、Interaction Domain、Custom Domain#

OIDC の Canonical Issuer (https://id.zeroword.smartcrab.ai/e/<environmentId>) は Environment 固有で変更しない。Production の形式は次のとおりである。

https://id.zeroword.smartcrab.ai/e/<environmentId>

Hosted Login は Zeroword の認証画面であり、Interaction Domain は Hosted Login、Public Authentication API、association files を提供する host である。既定値の Default Interaction Domain は env-<environmentId の env_ 以降>.login.zeroword.smartcrab.ai であり、OIDC metadata の issuer は引き続き Canonical Issuer を示す。

Public Authentication API は Hosted Login を使わずに独自の認証 UI を構築するための API であり、Interaction Domain または Canonical Issuer alias の /v1 path から利用する。

rp_enabled が有効な active Custom Domain があれば、その hostname が Interaction Domain と RP ID の両方になる。Custom Domain の切り替え時に Canonical Issuer は変わらない。Authorization Server から Hosted Login への移動は署名済みの短命・一回限り transaction に基づく。

RP ID は Passkey credential が束縛される WebAuthn hostname である。Production で Custom Domain を使う場合は、最初の Passkey 登録前に Custom Domain の設定を完了させる。RP ID を後から変更すると、旧 RP での再認証と新 RP での Passkey 登録を含む移行が必要になる。

Session と token#

Hosted Login / 認証操作用の Login Session と、顧客 API 用の OIDC token は別の仕組みである。

Web BFF の @auth-platform/server は refresh token を暗号化した HttpOnly session cookie 内に保持し、アプリケーションへ公開する session view からは refresh token と raw ID token を除外する。Access token は最大 5 分で自然失効する。個別 session は失効でき、全 session の無効化は user の security version を更新する。即時の失効判定が必要な Resource Server は introspection endpoint を使う。

MAU と課金の基本#

1 MAU は、Production Environment で請求月中に初めて成功した一意の End User である。対象は interactive login または refresh token exchange である。Test Environment、失敗ログイン、UserInfo、JWKS 取得、Access token 検証、管理メンバー、Management API key、Webhook は数えない。

集計の単位は Workspace / Environment / 請求月 / User ID である。同じ Environment の Web と React Native が同じ User ID を使えば 1 MAU、Environment が異なれば別々に数える。

• Workspace ごとに月 30,000 MAU までは無料で、カード登録を必要としない。
• 無料枠の 80%、95%、100% 到達時に Owner / Billing role へ通知する。
• 30,000 MAU を超えて使うには Stripe Customer、Subscription、Payment Method を有効にする。
• 未課金 Workspace の MAU が 30,000 を超えた場合、既存ユーザーの login は継続する。72 時間の grace period 後も課金設定がなければ、新規ユーザー作成だけが停止する。
• 課金開始時は当月 ledger を Stripe へ backfill する。Stripe 障害は認証 hot path を止めない。