メインコンテンツまでスキップ

独自 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 アセットのアップロード​

注記:

本番環境でこの機能を利用する際は注意してください。即座にユーザーのサインイン体験に影響します。

  1. コンソール > サインイン & アカウント > ブランディング > 独自 UI の持ち込み

     に移動します。
  2. 前の手順で作成した zip ファイルをクリックして選択、またはドラッグ＆ドロップすると、アップロードが自動的に開始されます。
  3. アップロードが完了したら変更を保存してください。カスタム UI が即座に提供されます。
  4. 独自のサインイン UI を使用している場合、「サインインプレビュー」ウィンドウは無効になります。ただし、 ライブプレビュー ボタンをクリックして、新しいブラウザタブでカスタムサインインページをテストできます。

カスタム CSP ソースを設定する​

Logto はカスタム UI ページに Content Security Policy (CSP) ヘッダーを適用します。カスタム UI がサードパーティスクリプトを読み込む場合や外部サービスへ接続する場合は、コンソール > サインイン & アカウント > ブランディング > 独自 UI の持ち込み で追加の許可ソースを設定できます。

設定できる項目:

  • script-src: CAPTCHA、分析ツール、タグマネージャーなどの JavaScript module または script のソースを許可します。
  • connect-src: fetch、XMLHttpRequest、EventSource、WebSocket 接続で使用するネットワークエンドポイントを許可します。

例:

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

どちらの directive も HTTPS origin を使用してください。WebSocket 接続の場合、connect-src は wss:// origin も受け付けます。Logto はカスタム UI アセットが有効な場合にのみ、これらのソースを既存のセキュリティポリシーへ追加します。

カスタム UI の開発​

Experience API との連携​

カスタム UI では、 Experience API と連携して、サインイン、サインアップ、パスワードリセット、ソーシャルアカウントの連携、多要素認証 (MFA) の有効化など、さまざまなアクションを実行する必要があります。ユーザーフローや実装の詳細をより深く理解するために、 Experience API 設計 RFC をご覧ください。包括的な技術仕様とサンプルが掲載されています。

また、 サインイン体験 API エンドポイント を通じて、ブランディングカラー、会社ロゴ、ファビコン、パスワードポリシー、ローカライズされた言語フレーズ、カスタム CSS など、他のサインイン体験設定にもアクセスできます。

CAPTCHA 有効時の対応​

組み込みの Logto サインイン体験では CAPTCHA を自動的に処理します。テナントが「独自 UI の持ち込み」を利用し、CAPTCHA ボット対策を有効にしている場合、カスタム UI で PUT /api/experience を呼び出す前にフロントエンドで CAPTCHA 連携を完了する必要があります。

プロバイダーから返されたトークンを captchaToken として PUT /api/experience リクエストボディに含めて送信してください。詳細は各プロバイダーのガイドを参照してください：

サンプルプロジェクト​

カスタム UI の理解と実装を素早く始められるよう、サンプルプロジェクトを用意しています。詳細は Logto Experience プロジェクト の 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 samples

Logto Cloud への独自サインイン UI の持ち込み