Pular para o conteúdo principal

Personalize a Página de Login no Casdoor: Estilização Personalizada da UI de Autenticação Sem Fork

· Leitura de 11 min
Yang Luo
Yang Luo
Casdoor Maintainer

Sim, o Casdoor suporta estilização personalizada de sua interface de autenticação, e você não precisa fazer um fork do frontend para isso. Cada aplicação possui uma aba UI Customization onde você define o logo, favicon, imagem de fundo, CSS personalizado para desktop e mobile, a posição do formulário, um painel lateral, HTML de rodapé e um tema. Duas tabelas, Signin items e Signup items, determinam quais campos são exibidos nas páginas de login e cadastro, em qual ordem, com quais rótulos e placeholders. Tudo é armazenado por aplicação no banco de dados, permitindo que uma instância do Casdoor atenda várias páginas de login com marcas diferentes, e os administradores da organização podem editar suas próprias páginas dentro de limites seguros.

O que alterar e onde​

O que você deseja alterarOnde no CasdoorDocs
Cor primária, raio dos cantos, estilo escuro ou compactoTheme da organização, ou da aplicação com Follow organization theme desativadoCustomize the theme
Um visual completo pronto para usoIdentity → Marketplace, temas de loginMarketplace
Logo, logo escuro, favicon, título da páginaPágina de edição da aplicaçãoApplication settings
Imagem de fundo (desktop e celular)Background URL, Background URL MobileUI customization
Aparência do formulárioCustom CSS, Custom CSS MobileUI customization
Formulário à esquerda, centro ou direita, ou ao lado de um painelForm position, Side panel HTMLUI customization
Texto abaixo do formulárioFooter HTMLApplication settings
Quais campos a página de login exibe, ordem, placeholdersSignin itemsSign-in items table
Senha, código, link mágico, WebAuthn, LDAP e sua ordemSignin methodsSign-in methods
Campos de cadastro, flags obrigatórias, rótulos, regexSignup itemsSign-up items table
Seletor de idiomaItem de login Languages, Languages da organizaçãoSign-in items table
Permitir que usuários escolham ou digitem sua organizaçãoOrg choice modeSpecify login organization

No console em chinês, a aba se chama 界面定制 e a tabela de itens de login se chama 登录项, então, se você está procurando como mudar a tela de login (登录界面) de uma aplicação, comece por lá.

Temas: Organização, Aplicação e Marketplace​

A mudança mais rápida é o tema. Um tema no Casdoor é um pequeno objeto com um estilo (Default, Dark, Document ou Blossom no editor), uma cor primária, um raio de borda e um interruptor compacto. Você pode defini-lo na organização, onde ele se aplica ao console para seus membros e às páginas de entrada de todas as aplicações que seguem o tema da organização, ou em uma única aplicação desativando Follow organization theme. A página de edição da aplicação tem uma prévia ao vivo, então você pode ver o resultado antes de salvar.

Se você quiser mais do que cores, o Casdoor Marketplace tem temas de login. Instalar um deles escreve os dados do tema, posição do formulário, CSS do formulário para desktop e mobile, HTML do painel lateral, HTML do rodapé e URLs de fundo de uma aplicação. O repositório casdoor-integrations atualmente contém 24 temas, desde Midnight e Split até Terminal, Nord e Solarized. Desinstalar um tema restaura o que a aplicação tinha antes, então tentar um não custa nada. Navegue por eles em marketplace.casdoor.com.

Branding: logo, favicon e fundo​

Cada aplicação tem seu próprio Logo, Favicon e Title, separados da organização. Uma organização pode executar vários produtos que compartilham usuários, mas mostram logos diferentes. Há também um opcional Logo dark, mostrado quando a página está no modo escuro; sem ele, o Casdoor continua usando o logo normal.

Background URL define a imagem atrás do formulário. Defina Background URL Mobile também se a imagem de desktop for cortada incorretamente em celulares. A prévia atualiza assim que a URL carrega.

CSS personalizado e layout do formulário​

Custom CSS aceita regras CSS simples; o Casdoor as envolve em um elemento style automaticamente, então não adicione um seu. Os principais contêineres para mirar são .login-panel e .login-form:

.login-panel {
  border-radius: 12px;
  background-color: #ffffff;
  box-shadow: 0 0 30px 20px rgba(0, 0, 0, 0.2);
}

Custom CSS Mobile contém regras para celulares, para que você não precise escrever media queries para o caso comum.

Form position coloca o formulário à esquerda, centro ou direita. A quarta opção, Enable side panel, centraliza o formulário e coloca um painel ao lado cujo conteúdo vem de Side panel HTML. Esse campo aceita HTML, então um elemento style dentro dele é permitido.

Footer HTML é renderizado abaixo dos formulários de login e cadastro. Se a aplicação for a aplicação padrão de sua organização, seu rodapé também substitui "Powered by Casdoor" no console de administração para os usuários daquela organização.

Quando estiver satisfeito com um design no ambiente de staging, Export JSON na parte inferior da página de edição da aplicação copia a aparência (logo, favicon, fundos, CSS, posição do formulário, painel lateral, tema e os campos de HTML personalizados) para a área de transferência, e Import JSON na mesma aplicação em outra instância aplica isso. A exportação não contém segredos ou provedores.

Campos, rótulos e ordem​

A tabela Signin items lista cada elemento da página de login: o logotipo, os campos de usuário e senha, o link para esqueci a senha, a caixa de seleção de termos, o seletor de idioma, o captcha, os botões de provedores e assim por diante. Para cada linha, você pode definir Visible, um Placeholder personalizado, Custom CSS por item e uma regra, além de movê-la para cima ou para baixo. Você também pode adicionar itens personalizados cujo rótulo seja HTML.

Algumas regras que vale a pena conhecer:

  • Ocultar Forgot password? desativa a redefinição de senha na API também, não apenas o link.
  • A regra Captcha alterna entre um captcha pop-up e um inline. Se você estiver escolhendo um provedor de captcha, consulte CAPTCHA providers compared for login pages.
  • A regra Languages alterna entre um ícone de globo e um seletor com rótulos. A própria lista é limitada aos Languages da organização, então uma organização que atende apenas usuários de inglês e japonês mostra apenas esses dois.

Os métodos de entrada (senha, código de verificação, magic link, WebAuthn, LDAP, Face ID e outros) estão em uma tabela separada, Signin methods, com sua própria ordem e nomes de exibição.

A tabela Signup items faz o mesmo para o registro, com Required, validação Regex, Label personalizada e regras como "No verification" para e-mail. POST /api/signup também limpa todos os campos cujo item está oculto, para que os clientes da API não possam definir campos que seu formulário não mostra. Prompted solicita aos usuários os campos ausentes, como número de telefone, após eles entrarem através de um provedor que não forneceu um.

Especifique a organização de login​

Se várias organizações compartilham um Casdoor, os usuários precisam de uma maneira de chegar à certa. O modo Org choice mode na aplicação padrão de uma organização (ou em app-built-in) adiciona uma etapa de organização ao /login: Input mostra um campo de texto, Select mostra um menu suspenso. Depois que o usuário escolhe, o Casdoor o envia para /login/<organization>, que mostra a página estilizada daquela organização. O navegador lembra a última organização em localStorage, então um usuário cuja sessão do console expirou chega novamente à sua própria página de login.

O que os administradores de tenant podem alterar com segurança​

Permitir que cada cliente personalize sua própria página de login levanta uma questão óbvia: o que impede um administrador da organização de adicionar um script que copia senhas, ou um seletor CSS que vaza cada caractere digitado através de requisições de imagem de fundo? O Casdoor verifica isso no servidor. Quando um administrador que não é um administrador global adiciona ou salva uma aplicação, cada campo HTML e CSS personalizado que foi alterado é validado, e o salvamento é rejeitado se qualquer um deles violar as regras:

  • O HTML só pode usar elementos de layout e texto, como div, span, p, títulos, listas, links, imagens, tabelas, style e formas SVG básicas. script, form, input e iframe são recusados, assim como manipuladores de eventos on..., atributos srcset, formaction, srcdoc e similares. href é permitido apenas em links com URLs relativas, http, https, mailto ou tel.
  • O CSS não pode conter barras invertidas, <, image(, image-set( e algumas outras funções. Cada url() deve ser relativa, uma URL data: ou começar com um prefixo permitido: Google Fonts, Fontsource no jsDelivr, as CDNs do Casdoor, a origem do próprio Casdoor, os domínios dos provedores de armazenamento globais ou uma entrada de formCssAllowedUrls.
  • @import é permitido apenas de Google Fonts e Fontsource, porque uma folha de estilo importada não é verificada em si.

Para permitir que os tenants carreguem imagens do seu próprio host, adicione-o ao conf/app.conf (consulte Configuration):

formCssAllowedUrls = "https://img.example.com/"

Além da verificação no momento do salvamento, as páginas de entrada sanitizam o HTML personalizado antes de renderizá-lo, a menos que a aplicação pertença à organização built-in ou um administrador global tenha ativado Enable custom scripts para ela. Apenas um administrador global pode ativar essa opção e, enquanto ela estiver ativa, apenas um administrador global pode alterar o HTML dessa aplicação. As mesmas regras se aplicam quando um tenant instala um tema do Marketplace: um tema que viole essas regras só pode ser instalado por um administrador global.

Signin HTML e Signup HTML merecem uma nota separada: eles substituem toda a página incorporada, incluindo o formulário. Como os tenants não podem adicionar formulários ou scripts, esses dois campos são principalmente para administradores globais; para branding, CSS, o painel lateral e o rodapé são as melhores ferramentas.

Página de login hospedada ou sua própria UI?​

Você pode criar sua própria tela de login na API do Casdoor, mas a página hospedada geralmente é a melhor escolha. Com OAuth 2.0 ou OpenID Connect, os usuários digitam sua senha apenas na origem do Casdoor e sua aplicação recebe um código de autorização, nunca as credenciais. Captcha, MFA, provedores sociais e corporativos, esqueci a senha, validação de cadastro e o seletor de organização continuam funcionando sem código do seu lado, e continuam recebendo correções quando você atualiza o Casdoor. Uma UI personalizada precisa reimplementar cada um desses fluxos e coloca as senhas passando pelos seus próprios servidores. Guias para integrar a página hospedada em uma aplicação: Spring Boot SSO with OIDC e Nginx SSO authentication.

Outros provedores hospedados fazem a mesma troca. Idura Verify, por exemplo, permite adicionar uma URL de folha de estilo e HTML personalizado ao redor de sua caixa de login pelo dashboard, sob uma Content Security Policy estrita com uma lista explícita de origens de estilo para fontes e imagens. O formCssAllowedUrls do Casdoor desempenha o mesmo papel, com a diferença de que o Casdoor é open source e auto-hospedado, então você controla a lista.

Referências​