Bring your UI

Logto allows you to bring your own UI to completely replace the built-in sign-in experience interface, in addition to the pre-built UI customization options. This feature enables you to upload a zip file containing your custom UI assets (HTML, CSS, JavaScript, images, etc.), have it hosted on Logto Cloud servers, and use it as the sign-in experience for your tenant users.

note:

This feature requires your custom UI to be Single Page Application (SPA) compatible, and it's recommended to always use a production build for optimal performance.

Explore the custom UI feature in Logto Console

Get started with official project

The fastest way to initiate a custom sign-in UI is to clone the Logto experience project. This is the built-in Logto Sign-in Experience UI that covers all features and Logto's best practices. You can customize it to fit your needs.

After checking out the code, just simply run the following command to build the project:

pnpm install && pnpm build

note:

The whole Logto project is a pnpm monorepo, If you want to run the experience package standalone (without pnpm), replace workspace: dependencies in package.json with specific version numbers (like ^1.0.0).

After the build completes, you'll find all compiled assets in the dist directory. Then create a ZIP archive of the dist directory - this archive will be used for uploading to Logto Cloud later.

Custom UI assets requirements

Before uploading your custom UI assets, make sure they meet the following requirements:

• The upload assets should be packed as a single zip file.
• The zip file should contain an index.html file in the root directory.
• The zip file should not exceed 20MB in size.
• The zip file should not contain any file that exceeds 10MB in size.
• The zip file should not contain more than 200 files in total.

Upload your custom UI assets

note:

Proceed with caution when using this feature in production, since it will immediately affect your users' sign-in experience.

1. Navigate to Console > Sign-in & account > Branding > Bring your UI.
2. Click to select or drag and drop your zip file created in the previous step, and the upload process will start automatically.
3. Once the upload is complete, save the changes, and your custom UI will be served immediately.
4. The "Sign-in preview" window will be disabled when you use your custom sign-in UI. However, you can still click the "Live preview" button to test your custom sign-in page in a new opened browser tab.

Configure custom CSP sources

Logto applies a Content Security Policy (CSP) header to custom UI pages. If your custom UI loads third-party scripts or connects to external services, add the extra source origins in Console > Sign-in & account > Branding > Bring your UI.

You can configure:

• script-src: Allows JavaScript module or script sources, such as CAPTCHA, analytics, or tag manager providers.
• connect-src: Allows network endpoints used by fetch, XMLHttpRequest, EventSource, and WebSocket connections.

Example:

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

Use HTTPS origins for both directives. connect-src also accepts wss:// origins for WebSocket connections. Logto appends these sources to the existing security policy only when your custom UI assets are active.

Configure the Cross-Origin-Opener-Policy header

By default, Logto sends no Cross-Origin-Opener-Policy (COOP) header, so an app that opens the sign-in page in a popup can keep communicating with it through window.opener. If your apps don't sign users in through popups, you can isolate your custom sign-in UI from other browser windows. Choose a policy under Cross-Origin-Opener-Policy in Console > Sign-in & account > Branding > Bring your UI:

Option	Header sent	Effect
Not set (no header)	None	The default. Every popup-based integration keeps working.
same-origin-allow-popups	Cross-Origin-Opener-Policy: same-origin-allow-popups	Cuts off the window that opened the sign-in page. Popups your custom UI opens keep window.opener while they stay on other sites.
same-origin	Cross-Origin-Opener-Policy: same-origin	Also cuts off the popups your custom UI opens.

You can also set the crossOriginOpenerPolicy field with the update sign-in experience Management API. It accepts unsafe-none (the default, which sends no header), same-origin-allow-popups, and same-origin.

warning:

Before you choose a policy, check how your apps and your custom UI use popups:

• Apps that open the sign-in page in a popup and rely on window.opener, for example to receive the result through postMessage, stop working with either policy. Keep the default while you have such apps, or move them to a redirect-based sign-in flow first.
• Popups your custom UI opens lose window.opener once they navigate back to your custom UI, for example to a social sign-in callback page. Popups that stay on another site and send their result from there, such as a provider's own sign-in popup, keep working with same-origin-allow-popups. With same-origin, popups lose window.opener as soon as they open.

If you need a policy, prefer same-origin-allow-popups over same-origin.

Logto sends the header only while your custom UI assets are served. The built-in sign-in pages, the /oidc/* pages, and Account Center (/account) never send a COOP header, so security scanners may still report it as missing on those pages.

Develop your custom UI

Interact with Experience API

Your custom UI needs to interact with Experience API to perform various actions such as sign-in, sign-up, password reset, binding social accounts, enabling MFA, and more. To better understand the user flows and implementation details, we recommend checking out our Experience API design RFC which provides comprehensive technical specifications and examples.

You also need to access other Sign-in Experience configurations, such as branding colors, company logo, favicon, password policy, localized language phrases, even custom CSS, through the sign-in Experience API endpoint.

Handle CAPTCHA when enabled

The built-in Logto sign-in experience handles CAPTCHA automatically. If your tenant uses Bring your UI and enables CAPTCHA bot protection, your custom UI must complete the frontend CAPTCHA integration before calling PUT /api/experience.

Send the returned provider token as captchaToken in the PUT /api/experience request body. See the provider-specific guides for details:

• reCAPTCHA Enterprise with Bring your UI
• Cloudflare Turnstile with Bring your UI

Sample projects

We provide a collection of sample projects to help you understand and start implementing custom UI quickly. Please check out the Logto Experience project GitHub repo for details.

Moreover, we'll continue working on providing more simplified and scenario-based sample projects to cover the most common use cases. Stay tuned for our future updates!

Local development and debugging

For local development and debugging, we provide the Logto Tunnel CLI tool to:

• Proxy Experience API requests from your local machine to Logto Cloud endpoint.
• Test your custom UI implementation locally.

This allows users to test and debug custom UI locally before uploading to Logto Cloud.

Please refer to Debug and test your custom UI locally for more details.

Upload your custom UI assets using the CLI

In addition to uploading through the Console, you can also use the Logto CLI to upload custom UI assets. This is particularly useful for automated deployment workflows.

Please refer to Upload custom UI assets using CLI for more details.

Restore to Logto built-in sign-in experience

If you wish to restore to Logto's built-in sign-in experience, simply click the delete button on the Bring your UI card. After saving the changes, the sign-in experience UI will be reverted back to Logto's default.

Related resources

RFCS: Experience API

Experience samples Bring your own sign-in UI to Logto Cloud