独自 UI の持ち込み
Logto では、組み込みのサインイン体験インターフェースを完全に置き換える独自の UI を持ち込むことができます。これは、事前構築された UI カスタマイズオプションに加えて利用できる機能です。この機能により、カスタム UI アセット（HTML、CSS、JavaScript、画像など）を含む zip ファイルをアップロードし、 Logto Cloud サーバーでホスティングし、テナントユーザー向けの サインイン体験 として利用できます。
この機能を利用するには、カスタム UI がシングルページアプリケーション（SPA）互換である必要があります。最適なパフォーマンスのため、常に本番ビルドを使用することを推奨します。
Logto コンソールでカスタム UI 機能を試す
公式プロジェクトで始める
カスタムサインイン UI を素早く始める最も簡単な方法は、 Logto experience プロジェクト をクローンすることです。これは、すべての機能と Logto のベストプラクティスをカバーした組み込みの Logto サインイン体験 UI です。ニーズに合わせてカスタマイズできます。
コードをチェックアウトしたら、次のコマンドを実行してプロジェクトをビルドしてください：
pnpm install && pnpm build
Logto プロジェクト全体は pnpm モノレポ です。experience パッケージを単体で（pnpm なしで）実行したい場合は、package.json 内の workspace: 依存関係を特定のバージョン番号（例：^1.0.0）に置き換えてください。
ビルドが完了すると、すべてのコンパイル済みアセットが dist ディレクトリに生成されます。次に dist ディレクトリを ZIP アーカイブ化してください。このアーカイブを後で Logto Cloud へアップロードします。
カスタム UI アセットの要件
カスタム UI アセットをアップロードする前に、以下の要件を満たしていることを確認してください：
- アップロードするアセットは 1 つの zip ファイルにまとめてください。
- zip ファイルのルートディレクトリに
index.htmlファイルが含まれている必要があります。 - zip ファイルのサイズは 20MB を超えてはいけません。
- zip ファイル内のいずれかのファイルが 10MB を超えてはいけません。
- zip ファイル内のファイル総数は 200 個以内にしてください。
カスタム UI アセットのアップロード
本番環境でこの機能を利用する際は注意してください。即座にユーザーのサインイン体験へ影響します。
- コンソール > サインイン & アカウント > ブランディング > 独自 UI の持ち込み に移動します。
- 前のステップで作成した zip ファイルをクリックして選択、またはドラッグ＆ドロップすると、アップロードが自動的に開始されます。
- アップロードが完了したら変更を保存してください。カスタム UI が即座に提供されます。
- カスタムサインイン UI を利用している場合、「サインインプレビュー」ウィンドウは無効になります。ただし、ライブプレビュー ボタンをクリックして、新しいブラウザタブでカスタムサインインページをテストできます。
カスタム CSP ソースの設定
Logto はカスタム UI ページに Content Security Policy (CSP) ヘッダーを適用します。カスタム UI でサードパーティスクリプトを読み込んだり外部サービスへ接続する場合は、追加のソースオリジンを コンソール > サインイン & アカウント > ブランディング > 独自 UI の持ち込み で追加してください。
設定できる項目：
script-src: CAPTCHA、アナリティクス、タグマネージャーなどの JavaScript モジュールやスクリプトのソースを許可します。connect-src:fetch、XMLHttpRequest、EventSource、WebSocket 接続で使用されるネットワークエンドポイントを許可します。
例：
{
"scriptSrc": ["https://scripts.example.com"],
"connectSrc": ["https://api.example.com", "wss://events.example.com"]
}
両ディレクティブとも HTTPS オリジンを使用してください。connect-src では WebSocket 接続用に wss:// オリジンも利用できます。カスタム UI アセットが有効な場合のみ、Logto は既存のセキュリティポリシーにこれらのソースを追加します。
Cross-Origin-Opener-Policy ヘッダーの設定
デフォルトでは、Logto は Cross-Origin-Opener-Policy (COOP) ヘッダーを送信しません。そのため、サインインページをポップアップで開くアプリは window.opener を通じて通信を維持できます。アプリがポップアップを使わずにサインインする場合は、カスタムサインイン UI を他のブラウザウィンドウから分離できます。コンソール > サインイン & アカウント > ブランディング > 独自 UI の持ち込み の Cross-Origin-Opener-Policy でポリシーを選択してください：
| オプション | 送信されるヘッダー | 効果 |
|---|---|---|
| 未設定（ヘッダーなし） | なし | デフォルト。すべてのポップアップ連携が動作します。 |
same-origin-allow-popups | Cross-Origin-Opener-Policy: same-origin-allow-popups | サインインページを開いたウィンドウとの接続を切断します。カスタム UI が開いたポップアップは他サイト上にいる間 window.opener を維持します。 |
same-origin | Cross-Origin-Opener-Policy: same-origin | カスタム UI が開いたポップアップも接続を切断します。 |
また、 サインイン体験の更新 Management API で crossOriginOpenerPolicy フィールドを設定できます。unsafe-none（デフォルト、ヘッダーなし）、same-origin-allow-popups、same-origin が利用可能です。
ポリシーを選択する前に、アプリやカスタム UI がポップアップをどのように利用しているか確認してください：
- サインインページをポップアップで開き、
window.openerを利用して（例：postMessageで結果を受け取るなど）いるアプリは、いずれかのポリシーを設定すると動作しなくなります。そのようなアプリがある場合はデフォルトのままにするか、リダイレクトベースのサインインフローへ移行してください。 - カスタム UI が開いたポップアップは、カスタム UI に戻ると
window.openerを失います（例：ソーシャルサインインのコールバックページ）。他サイト上にとどまり、そこで結果を送信するポップアップ（プロバイダー独自のサインインポップアップなど）はsame-origin-allow-popupsで動作します。same-originでは、開いた時点でwindow.openerを失います。
ポリシーが必要な場合は、same-origin より same-origin-allow-popups を推奨します。
Logto はカスタム UI アセットが提供されている間のみヘッダーを送信します。組み込みサインインページ、/oidc/* ページ、Account Center (/account) では COOP ヘッダーは送信されません。そのため、セキュリティスキャナーでこれらのページにヘッダーがないと報告される場合があります。
カスタム UI の開発
Experience API との連携
カスタム UI では、 Experience API と連携してサインイン、サインアップ、パスワードリセット、ソーシャルアカウント連携、多要素認証 (MFA) 有効化など様々な操作を行う必要があります。ユーザーフローや実装詳細を理解するため、 Experience API 設計 RFC をご参照ください。技術仕様やサンプルが網羅されています。
また、ブランドカラー、会社ロゴ、ファビコン、パスワードポリシー、多言語フレーズ、カスタム CSS など、他のサインイン体験設定にも sign-in Experience API endpoint を通じてアクセスできます。
CAPTCHA 有効時の対応
組み込みの Logto サインイン体験では CAPTCHA を自動で処理します。Bring your UI を利用し、CAPTCHA ボット対策を有効にしている場合は、PUT /api/experience を呼び出す前にフロントエンドで CAPTCHA 連携を完了する必要があります。
プロバイダーから返されたトークンを captchaToken として PUT /api/experience リクエストボディに含めてください。詳細は各プロバイダーのガイドを参照してください：
サンプルプロジェクト
カスタム UI の理解と実装を素早く始められるよう、サンプルプロジェクトを用意しています。詳細は Logto Experience project GitHub リポジトリをご覧ください。
今後も、よりシンプルでシナリオベースのサンプルプロジェクトを追加し、一般的なユースケースをカバーしていく予定です。今後のアップデートにご期待ください！
ローカル開発とデバッグ
ローカル開発やデバッグのために、Logto Tunnel CLI ツールを提供しています。これにより：
- ローカルマシンから Logto Cloud エンドポイントへの Experience API リクエストをプロキシできます。
- カスタム UI 実装をローカルでテストできます。
これにより、Logto Cloud へアップロードする前にカスタム UI をローカルでテスト・デバッグできます。
詳細は カスタム UI をローカルでデバッグ・テストする をご参照ください。
CLI を使ったカスタム UI アセットのアップロード
コンソールからのアップロードに加え、Logto CLI を使ってカスタム UI アセットをアップロードすることもできます。これは自動デプロイワークフローに特に便利です。
詳細は CLI を使ったカスタム UI アセットのアップロード をご参照ください。
Logto 組み込みサインイン体験への復元
Logto の組み込みサインイン体験に戻したい場合は、「独自 UI の持ち込み」カードの削除ボタンをクリックしてください。変更を保存すると、サインイン体験 UI は Logto のデフォルトに戻ります。
関連リソース
RFCS: Experience API
Experience samplesLogto Cloud への独自サインイン UI の持ち込み