ホワイトラベル AI API エンドポイント: カスタム ドメイン、TLS 自動化、テナントセーフ ルーティング

ゲートウェイを指す顧客の CNAME は、本番環境に対応したブランドのエンドポイントを作成しません。 DNS レコードは証明書が利用可能になる前に解決される可能性があり、証明書は検証レコードがそのまま残っている間のみ更新される可能性があり、チェックされていない Host ヘッダーによりリクエストが間違ったテナント コンテキストにルーティングされる可能性があります。

より安全なモデルは、すべてのブランドのホスト名を永続的なコントロール プレーン リソースとして扱うことです。所有権、証明書の発行、DNS カットオーバー、ルーティングのアクティブ化、一時停止、および削除には、それぞれ明示的な状態が必要です。リクエスト時に、ホスト名によって許可されるテナント コンテキストが絞り込まれますが、API キーは承認境界のままです。

ドメインのライフサイクルを独立したチェックに分離します

カスタム ドメインを verified などの単一のブール値で表さないでください。少なくとも 4 つの独立した条件を追跡します:

• 所有権: 顧客がホスト名を制御していることが証明されましたか?
• 証明書: 有効な証明書が発行され、エッジに展開されましたか?
• DNS: 権威 DNS が予想されるゲートウェイを指しているかターゲット?
• ルーティング: 正確なホスト名はアクティブなテナントとルーティング プロファイルにバインドされていますか?

この分離は、文書化されたエッジ プロバイダーの動作を反映しています。管理されたカスタムホスト名製品は、ホスト名の所有権と証明書の検証にさまざまなレコードとステータスを使用できます。したがって、DNS 解決だけでは、エンドポイントの準備ができていることを証明することはできません。

実際のステート マシンは次のとおりです。

requested
  -> ownership_pending
  -> certificate_pending
  -> dns_pending
  -> ready
  -> suspended
  -> draining
  -> deleted

これらはビジネス状態であり、プロバイダーのステータスを直接コピーしたものではありません。プロバイダーの生の状態を個別に保存し、文書化された不変条件に従って独自の状態を導出します。たとえば、所有権が有効で、証明書がアクティブで、DNS が予想されるターゲットを指し、エッジ ルートが有効な場合にのみ、ドメイン ready をマークします。

推奨事項: 初期アクティブ化中の遷移は単調にします。一時的に成功した TLS プローブでは、所有権の検証やルーティング チェックをスキップしないでください。アクティベーション後、調整によってドメインが ready から suspended に移行するか、これらの不変条件が保持されなくなったときに明示的な劣化状態に移行する可能性があります。

ドメインをファーストクラスのリソースとして保存する

運用可能なホワイトラベル AI API ゲートウェイ のドメイン レコードには、あいまいな API 呼び出しとプロバイダーから回復するのに十分な情報が含まれている必要があります。 drift:

{
  "domain_id": "dom_01J...",
  "hostname_ascii": "api.customer.example",
  "tenant_id": "ten_01H...",
  "brand_id": "brand_42",
  "state": "certificate_pending",
  "ownership_method": "dns_txt",
  "ownership_record": {
    "name": "_gateway-verify.api.customer.example",
    "value": "verify=..."
  },
  "certificate_status": "pending_validation",
  "expected_cname": "customers.edge.example",
  "routing_profile_id": "route_openai_compatible_v3",
  "provider_hostname_id": "edge_8f2...",
  "creation_operation_id": "op_01J...",
  "last_reconciled_at": "2026-11-02T10:00:00Z",
  "last_reconciliation_result": "certificate_pending"
}

一意性チェックの前に、IDNA 対応ライブラリを使用してホスト名を小文字の ASCII に正規化します。末尾のドットを削除し、明示的にサポートされていない限り、IP リテラル、URL パス、ポート、ワイルドカード、および受け入れられたパブリック サフィックス ポリシー外の名前を拒否します。送信された表示フォームは、権限のないメタデータとしてのみ保存してください。

正規化されたホスト名にグローバルな一意性制約を適用します。 2 つのテナントが、異なる大文字や Unicode 表現を使用している場合でも、同じ権限を主張することはできません。

本番 DNS を変更する前に事前検証を行う

エッジ プラットフォームが証明書をサポートしている場合は、顧客に本番 CNAME の変更を求める前に、証明書を発行してデプロイします。一般的なシーケンスは次のとおりです。

1. 冪等キーを使用してドメイン リソースを作成します。
2. 所有権と証明書検証レコードを返します。
3. 両方の検証が成功するまでプロバイダ イベントをポーリングまたは受信します。
4. 証明書が正確なホスト名にデプロイされていることを確認します。
5. ゲートウェイで運用 CNAME を指すように顧客に依頼します。 target.
6. 複数のネットワークの場所から権威 DNS を解決します。
7. ルートを有効にして、認証されたエンドツーエンド プローブを実行します。
8. ドメイン ready をマークします。

事実: マネージド SaaS エッジのドキュメントには、検証と証明書の発行は、運用環境の CNAME が変更される前に行われます。 トレードオフ: これにより、目に見える TLS アクティベーション ギャップは回避されますが、お客様は追加の TXT、CNAME、または委任された検証レコードを作成する必要があります。

事前検証が利用できない場合は、中断の可能性を明示的に公開します。トラフィックが移動した後でのみ証明書の発行が開始される場合は、ダウンタイムがゼロであることを約束しないでください。

正確な権限によってルーティングし、キーを承認します

信頼できるエッジは、ホスト名から許可されたテナントまたはブランド コンテキストまでの正確な許可リストを維持する必要があります:

api.customer.example -> {
  tenant_id: "ten_01H...",
  brand_id: "brand_42",
  state: "ready"
}

未知、非アクティブ、およびあいまいな権限を拒否します。デフォルトのテナントには決して送信しないでください。 HTTP/1.1 の場合、Host を検証します。 HTTP/2 および HTTP/3 については、:authority を検証します。 TLS が同じエッジで終端される場合は、リクエストの認証局を、プロキシによってサポートされている SNI および証明書コンテキストと比較します。

転送ヘッダーには同じ規律が必要です。パブリック エッジは、受信 X-Forwarded-Host、Forwarded、および内部テナント ヘッダーを削除してから、正規ホストと解決されたテナント信号を追加する必要があります。オリジンは、認証されたエッジからオリジンへの接続を介してのみこれらの信号を受け入れる必要があります。

実行時の認証シーケンスは次のようにする必要があります。

1. アクティブなホスト名の許可リストを通じて正規化された権限を解決します。
2. API キーを個別に認証します。
3. key.
4. キーのテナントが解決されたホスト名で許可されていることを確認します。
5. テナント ID とキー ID を使用して、モデル、予算、レート制限、およびルーティング ポリシーを適用します。
6. ホスト名ではなく、それらの不変 ID に対して使用状況レコードを書き込みます。

これにより、パートナーの役割が保持されますAPI 自動化。ドメイン管理操作を認証ショートカットに変換する必要はありません。

認証が設定されたオリジンまたは接続コンテキストと一致しない場合は、421 Misdirected Request を返します。ホスト名は有効だが、認証されたキーが使用を許可されていないテナントに属している場合は、403 Forbidden を返します。どのテナントがホスト名を所有しているかを明らかにしないように、エラー本文は汎用的なものにしてください。

正規エンドポイントとブランド エンドポイントの互換性

一部のお客様は、ゲートウェイの正規エンドポイントとブランド エンドポイントの両方で動作するために 1 つのキーを必要とします。これは、両方のホスト名が同じ承認されたテナント コンテキストに解決される場合にのみ許容されます。各キーを 1 つのホスト名に厳密にバインドすると、ブランド間の使用は減りますが、移行やエンドポイント間で切り替えるクライアントが複雑になります。

推奨事項: モデルでは、アプリケーション コード内の文字列を比較するのではなく、キー ポリシーとしてエンドポイント コンテキストを許可します。たとえば、キーでは tenant:any-active-hostname、brand:brand_42、または 1 つの正確な domain_id を許可できます。

パートナーを通じてライフサイクル操作を公開します。API

最小限の API は、作成、検査、再検証、一時停止、再開、削除をサポートする必要があります。

POST   /partner/v1/custom-domains
GET    /partner/v1/custom-domains/{domain_id}
POST   /partner/v1/custom-domains/{domain_id}/revalidate
POST   /partner/v1/custom-domains/{domain_id}/suspend
POST   /partner/v1/custom-domains/{domain_id}/resume
DELETE /partner/v1/custom-domains/{domain_id}

作成および削除操作は、安定した冪等キーを受け入れる必要があります。プロバイダー API、DNS 伝播、およびネットワーク タイムアウトにより、呼び出し元は操作が成功したかどうか確信が持てなくなる可能性があります。エッジ プロバイダを呼び出す前に操作レコードを保持し、同じキーと同等のペイロードでリクエストが再試行されたときに同じドメインまたは削除操作を返します。

custom_domain.verification_required、custom_domain.certificate_active、custom_domain.ready、custom_domain.dns_drifted、custom_domain.renewal_at_risk、custom_domain.deleted などの署名付きライフサイクル イベントを発行します。イベントは通知であり、唯一の真実の情報源ではありません。消費者は、配信の欠落または重複後に現在の状態を取得できる必要があります。

DNS、証明書、ルーティングを継続的に調整します

アクティベーションはライフサイクルの終わりではありません。 DNS レコードが編集され、検証レコードが失われ、エッジ構成にドリフトがあり、証明書が更新に近づいています。

以下をチェックする定期的なリコンサイラーを実行します。

• 権威 DNS と予想される CNAME または委任されたターゲット
• プロバイダーのホスト名と証明書のステータス
• 証明書の名前、有効期限、更新health
• 必要な DNS 検証レコードの存在
• 正確なエッジ ルートの所有権とアクティベーション状態
• トラフィックを処理するためのテナントの現在の資格

DNS 検証済みの証明書の自動化は、公的に解決可能な検証 CNAME レコードに依存する場合があります。自動更新が常に成功すると仮定するのではなく、有効期限が切れる前にアラートを出します。

証明書操作には指数バックオフとジッターを備えた制限付き再試行を使用します。発行を直接操作する ACME アカウントと注文状態を保持します。削除と再作成を繰り返すと、証明書の順序または登録済みドメインのレート制限が消費される可能性があります。保留中のホスト名レコードも、明示的に削除されるまでプロバイダの割り当てを消費する可能性があります。

運用予測: 調整が行われない場合、最も一般的な失敗は、オンボーディングが成功した後、DNS 編集、証明書の更新、プロバイダ側のドリフト、または顧客の離脱中に発生します。これは、測定された障害率ではなく、アーキテクチャ上の予想です。

2 つのフェーズでオフボード

最初にデータベース行を削除すると、エッジ マッピング、証明書、または DNS が存続する可能性があるため、安全ではありません。監査可能な 2 フェーズのワークフローを使用します。

1. ドメインを draining に移動し、新しい統合のアドバタイズを停止します。
2. 既存のリクエストが短い猶予期間を受けるか、即時に拒否されるかを決定します。
3. ホスト名がデフォルト テナントに解決されないようにエッジ ルートを無効にします。
4. カスタム ホスト名と証明書の関連付けを
5. お客様に、DNS レコードを削除または置き換えるように依頼します。
6. DNS がサービスを指していないことを確認します。
7. 識別子と監査レコードを保持しながら、リソース deleted にマークを付けます。

プロビジョニング解除されたサービスをターゲットとするぶら下がり CNAME は、サブドメイン乗っ取りのリスクを引き起こす可能性があります。逆に、古いマッピングをアクティブのままにしておくと、元の顧客のトラフィックがエッジ経由で送信され続ける可能性があります。プロバイダのクリーンアップと DNS 検証を同じ削除操作に結合しますが、それぞれの結果を個別に記録します。

ハッピー パスだけでなく境界をテストする

顧客ドメインを有効にする前に、次の適合性テストを自動化します。

• 偽造された Host または X-Forwarded-Host ヘッダー
• 競合する SNI と HTTP 権限値
• 不明なホスト名と既知だが停止中のホスト名
• テナント A の有効なキーがテナント B のホスト名で使用されている
• 同じ冪等キーを持つ重複した作成リクエストと削除リクエスト
• 大文字小文字、末尾のドット、または Unicode のバリエーションを使用して送信された同じホスト名
• DNS が変更されましたアクティベーション後の予想されるターゲット
• 更新前に削除された証明書検証レコード
• エッジ マッピングが削除された後、DNS が変更される前に削除が中断されました

また、ログ、請求、使用量の属性、レート制限、およびポリシーの決定でテナント ID とキー ID が使用されていることを確認します。ホスト名は変更可能なプレゼンテーションおよびルーティング入力です。

実装チェックリスト

• ホスト名を正規化し、グローバルな一意性を適用します。
• 所有権、証明書、DNS、およびルートの準備状況を個別に追跡します。
• サポートされている場合はカットオーバー前に証明書を事前検証します。
• 許可リストは正確です
• 信頼できない転送ヘッダーを削除し、認証された送信元信号を作成します。
• ホスト名のテナント コンテキストに対して API キーを承認します。
• 送信元または接続の不一致には 421 を使用し、テナント間のキーの使用には 403 を使用します。
• 作成と削除を行うべき等。
• プロバイダの状態、DNS、ルーティング、および更新の健全性を継続的に調整します。
• エッジ マッピングを明示的に削除し、オフボード中に DNS を検証します。

ブランド エンドポイントは、コントロール プレーンの状態とデータ プレーンの動作が一致する場合にのみ準備が整います。その合意を明示的にモデル化し、ネガティブ パスをテストし、API キーを最終テナント認証境界として保持します。

関連資料

• べき等パートナー API の操作