Traga sua própria UI

O Logto permite que você traga sua própria interface de usuário (UI) para substituir completamente a interface de experiência de login integrada, além das opções de personalização de UI pré-construídas. Esse recurso permite que você faça upload de um arquivo zip contendo seus ativos de UI personalizados (HTML, CSS, JavaScript, imagens, etc.), hospede-os nos servidores do Logto Cloud e os utilize como a experiência de login para os usuários do seu tenant.

nota:

Esse recurso exige que sua UI personalizada seja compatível com Single Page Application (SPA), e é recomendado sempre usar uma build de produção para melhor desempenho.

Explore o recurso de UI personalizada no Logto Console

Comece com o projeto oficial

A maneira mais rápida de iniciar uma UI de login personalizada é clonar o projeto Logto experience. Esta é a UI de Experiência de Login integrada do Logto que cobre todos os recursos e as melhores práticas do Logto. Você pode personalizá-la conforme suas necessidades.

Após baixar o código, basta executar o seguinte comando para construir o projeto:

pnpm install && pnpm build

nota:

Todo o projeto Logto é um monorepo pnpm. Se você quiser rodar o pacote experience de forma independente (sem pnpm), substitua as dependências workspace: no package.json por números de versão específicos (como ^1.0.0).

Após a conclusão da build, você encontrará todos os ativos compilados no diretório dist. Em seguida, crie um arquivo ZIP do diretório dist — esse arquivo será usado para upload no Logto Cloud posteriormente.

Requisitos dos ativos de UI personalizada

Antes de fazer upload dos seus ativos de UI personalizada, certifique-se de que eles atendam aos seguintes requisitos:

• Os ativos enviados devem ser compactados em um único arquivo zip.
• O arquivo zip deve conter um arquivo index.html no diretório raiz.
• O arquivo zip não deve exceder 20MB de tamanho.
• O arquivo zip não deve conter nenhum arquivo que exceda 10MB de tamanho.
• O arquivo zip não deve conter mais de 200 arquivos no total.

Faça upload dos seus ativos de UI personalizada

nota:

Tenha cautela ao usar esse recurso em produção, pois ele afetará imediatamente a experiência de login dos seus usuários.

1. Navegue até Console > Login & conta > Branding > Traga sua UI.
2. Clique para selecionar ou arraste e solte seu arquivo zip criado na etapa anterior, e o processo de upload começará automaticamente.
3. Assim que o upload for concluído, salve as alterações e sua UI personalizada será disponibilizada imediatamente.
4. A janela "Pré-visualização do login" será desabilitada quando você usar sua UI de login personalizada. No entanto, você ainda pode clicar no botão "Pré-visualização ao vivo" para testar sua página de login personalizada em uma nova aba do navegador.

Configure fontes CSP personalizadas

O Logto aplica um cabeçalho Content Security Policy (CSP) às páginas de UI personalizada. Se sua UI personalizada carregar scripts de terceiros ou se conectar a serviços externos, adicione as origens extras em Console > Login & conta > Branding > Traga sua UI.

Você pode configurar:

• script-src: Permite fontes de módulos ou scripts JavaScript, como CAPTCHA, analytics ou provedores de tag manager.
• connect-src: Permite endpoints de rede usados por fetch, XMLHttpRequest, EventSource e conexões WebSocket.

Exemplo:

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

Use origens HTTPS para ambas as diretivas. connect-src também aceita origens wss:// para conexões WebSocket. O Logto adiciona essas fontes à política de segurança existente somente quando seus ativos de UI personalizada estão ativos.

Configure o cabeçalho Cross-Origin-Opener-Policy

Por padrão, o Logto não envia o cabeçalho Cross-Origin-Opener-Policy (COOP), então um app que abre a página de login em um popup pode continuar se comunicando com ela através do window.opener. Se seus apps não fazem login de usuários por popups, você pode isolar sua UI de login personalizada de outras janelas do navegador. Escolha uma política em Cross-Origin-Opener-Policy em Console > Login & conta > Branding > Traga sua UI:

Opção	Cabeçalho enviado	Efeito
Não definido (sem cabeçalho)	Nenhum	Padrão. Toda integração baseada em popup continua funcionando.
same-origin-allow-popups	Cross-Origin-Opener-Policy: same-origin-allow-popups	Desconecta a janela que abriu a página de login. Popups abertos pela sua UI personalizada mantêm window.opener enquanto estiverem em outros sites.
same-origin	Cross-Origin-Opener-Policy: same-origin	Também desconecta os popups abertos pela sua UI personalizada.

Você também pode definir o campo crossOriginOpenerPolicy com a API de gerenciamento update sign-in experience. Aceita unsafe-none (padrão, não envia cabeçalho), same-origin-allow-popups e same-origin.

atenção:

Antes de escolher uma política, verifique como seus apps e sua UI personalizada usam popups:

• Apps que abrem a página de login em um popup e dependem do window.opener, por exemplo para receber o resultado via postMessage, param de funcionar com qualquer uma das políticas. Mantenha o padrão enquanto tiver tais apps, ou migre-os para um fluxo de login baseado em redirecionamento primeiro.
• Popups abertos pela sua UI personalizada perdem o window.opener assim que navegam de volta para sua UI personalizada, por exemplo para uma página de callback de login social. Popups que permanecem em outro site e enviam o resultado de lá, como o popup de login do próprio provedor, continuam funcionando com same-origin-allow-popups. Com same-origin, popups perdem o window.opener assim que são abertos.

Se precisar de uma política, prefira same-origin-allow-popups em vez de same-origin.

O Logto envia o cabeçalho apenas enquanto seus ativos de UI personalizada estão sendo servidos. As páginas de login integradas, as páginas /oidc/* e o Account Center (/account) nunca enviam um cabeçalho COOP, então scanners de segurança ainda podem reportar sua ausência nessas páginas.

Desenvolva sua UI personalizada

Interaja com a Experience API

Sua UI personalizada precisa interagir com a Experience API para realizar várias ações como login, cadastro, redefinição de senha, vinculação de contas sociais, habilitação de MFA, entre outras. Para entender melhor os fluxos de usuário e detalhes de implementação, recomendamos conferir nosso RFC de design da Experience API, que fornece especificações técnicas abrangentes e exemplos.

Você também precisará acessar outras configurações da Experiência de Login, como cores de branding, logo da empresa, favicon, política de senha, frases de idioma localizadas e até CSS personalizado, através do endpoint da Experience API de login.

Lide com CAPTCHA quando habilitado

A experiência de login integrada do Logto lida com CAPTCHA automaticamente. Se seu tenant usa o recurso Traga sua UI e habilita a proteção contra bots CAPTCHA, sua UI personalizada deve completar a integração do CAPTCHA no frontend antes de chamar PUT /api/experience.

Envie o token retornado pelo provedor como captchaToken no corpo da requisição PUT /api/experience. Veja os guias específicos dos provedores para detalhes:

• reCAPTCHA Enterprise com Traga sua UI
• Cloudflare Turnstile com Traga sua UI

Projetos de exemplo

Disponibilizamos uma coleção de projetos de exemplo para ajudar você a entender e começar a implementar sua UI personalizada rapidamente. Confira o repositório Logto Experience project no GitHub para mais detalhes.

Além disso, continuaremos trabalhando para fornecer mais projetos de exemplo simplificados e baseados em cenários para cobrir os casos de uso mais comuns. Fique atento às nossas próximas atualizações!

Desenvolvimento local e depuração

Para desenvolvimento local e depuração, fornecemos a ferramenta Logto Tunnel CLI para:

• Fazer proxy das requisições da Experience API da sua máquina local para o endpoint do Logto Cloud.
• Testar sua implementação de UI personalizada localmente.

Isso permite que os usuários testem e depurem a UI personalizada localmente antes de fazer upload para o Logto Cloud.

Consulte Depure e teste sua UI personalizada localmente para mais detalhes.

Faça upload dos seus ativos de UI personalizada usando o CLI

Além do upload pelo Console, você também pode usar o Logto CLI para enviar ativos de UI personalizada. Isso é especialmente útil para fluxos de implantação automatizados.

Consulte Faça upload de ativos de UI personalizada usando o CLI para mais detalhes.

Restaure para a experiência de login integrada do Logto

Se desejar restaurar a experiência de login integrada do Logto, basta clicar no botão de exclusão no card Traga sua UI. Após salvar as alterações, a UI da experiência de login será revertida para o padrão do Logto.

Recursos relacionados

RFCS: Experience API

Exemplos de experiência

Traga sua própria UI de login para o Logto Cloud