Keycloak: Personalizar a aparência

Personalize facilmente as páginas de login, o console de conta e os emails do Keycloak no Stackhero: defina as suas cores, logótipo, textos e até crie temas totalmente personalizados com o editor online integrado.

👋 Bem-vindo à documentação da Stackhero!

A Stackhero disponibiliza um serviço de Keycloak cloud que facilita o lançamento de um fornecedor de identidade pronto para produção em apenas 2 minutos:

• Utilizadores, realms e clientes em quantidade ilimitada
• Suporte para OpenID Connect, OAuth 2.0, SAML 2.0, login social, federação LDAP e Active Directory
• Nome de domínio personalizado com HTTPS integrado para acesso seguro (por exemplo, https://login.sua-empresa.com)
• Temas personalizados: personalize facilmente as suas páginas de login, consola de conta e emails com o editor online incluído
• Servidor de email dedicado com SPF, DKIM e DMARC, para que confirmações de conta e redefinições de palavra-passe sejam tratadas automaticamente
• Base de dados PostgreSQL integrada, com a consola de administração disponível num porto dedicado e amovível
• Atualizações com um clique para manter o sistema sempre atualizado sem intervenção manual

Dedique o seu tempo ao desenvolvimento, não à configuração: pode experimentar a solução Keycloak cloud da Stackhero em menos de 5 minutos.

Personalizar a aparência do seu Keycloak

A sua página de login é um dos primeiros elementos que os seus utilizadores veem. Com o Stackhero, pode personalizá-la em poucos minutos: defina as suas cores, logótipo e textos para cada idioma suportado. O mesmo se aplica aos emails enviados pelo Keycloak.

Existem duas ferramentas principais, ambas incluídas no seu serviço:

• O editor de temas, um editor de ficheiros online onde o seu tema está armazenado.
• Quick Theme, o designer visual de temas integrado na consola de administração do Keycloak, para escolher cores e identidade visual sem editar CSS.

Não é necessário SSH, recompilações ou reimplementações.

Aceder ao editor de temas

Na página do seu serviço no dashboard Stackhero encontrará um URL Themes editor junto à sua consola de administração:

https://your-domain.com:4443/stackhero_themes/

Inicie sessão com as suas credenciais de administrador do Keycloak: as mesmas que utiliza para a consola de administração.

Dois pontos importantes a ter em conta:

• O editor funciona na porta de administração, não na porta usada pelas suas aplicações. Se fechar essa porta no firewall do Stackhero, tanto a consola de administração como o editor ficam inacessíveis. As suas aplicações continuam a autenticar normalmente.
• Todas as alterações feitas aqui ficam guardadas no disco do seu serviço, são incluídas nos seus backups e persistem após reinícios e atualizações.

Encontrará dois diretórios:

Cada diretório inclui um ficheiro README.md com documentação atualizada correspondente à versão do seu serviço.

O seu tema está pronto a ser editado

Abra themes/ e encontrará um diretório default/. Este é o seu tema ativo, já em uso pela sua instância Keycloak. Não há nada para selecionar: basta editar os ficheiros e ver as alterações refletidas de imediato.

Não precisa de conhecimentos prévios sobre temas do Keycloak. Cada ficheiro já lista as definições mais comuns que pode querer alterar, mostrando o valor atual do Keycloak como exemplo comentado. Para atualizar um valor, remova o símbolo de comentário, ajuste o valor e guarde.

Se uma linha permanecer comentada, o Keycloak utiliza o valor por defeito. Isto garante que o seu serviço mantém sempre o comportamento padrão do Keycloak, mesmo após atualizações.

Atualizar o seu logótipo

Abra default/login/resources/img/. No interior, verá as duas imagens atualmente usadas na sua página de login. Carregue o seu próprio logótipo com o mesmo nome de ficheiro, keycloak-logo-text.svg, e atualize a página de login com Ctrl+F5 (Cmd+Shift+R no macOS).

É tudo o que precisa de fazer. Não é necessário editar ficheiros nem reiniciar o serviço: as alterações são aplicadas assim que guardar. Para alterar a imagem de fundo, substitua o ficheiro keycloak-bg-darken.svg na mesma pasta.

Se preferir usar outros nomes de ficheiro, pode atualizar as referências em default/login/resources/css/stackhero.css na secção "Your logo".

Definir as suas cores

Em stackhero.css, encontrará variáveis já preenchidas com os valores atuais:

:root {
  /* ---------- Colors ---------- */
  /* The buttons */
  /* --pf-v5-global--primary-color--100: #06c; */
  /* The buttons, while hovered */
  /* --pf-v5-global--primary-color--200: #004080; */
  /* The links */
  /* --pf-v5-global--link--Color: #06c; */
  /* The colored line on top of the login box */
  /* --keycloak-card-top-color: #06c; */

Para aplicar uma alteração, remova os símbolos de comentário, defina a sua cor, guarde e recarregue a página. Só isso.

Enquanto trabalha: O seu navegador faz cache do CSS, imagens e scripts do tema durante uma hora. Ao testar, recarregue sempre com Ctrl+F5 para ver as alterações mais recentes. Os seus visitantes verão as atualizações no prazo de uma hora.

Tem controlo total: o ficheiro é CSS puro e é carregado por último, permitindo-lhe sobrescrever qualquer estilo. Utilize as DevTools do navegador (F12) para inspecionar elementos. O Keycloak 26 utiliza o PatternFly design system, por isso a maioria das variáveis de cor são nomeadas --pf-v5-global--* e podem ser redefinidas em :root.

Definir o nome da sua empresa

Não é necessário editar o tema para isto. Na consola de administração, abra Realm settings > General e defina o Display name. Este nome será apresentado nas páginas de login e nos emails.

Alterar textos, em vários idiomas

Pode alterar os textos sem mexer em CSS ou HTML. Em default/login/messages/messages_en.properties, encontrará todos os textos do formulário de login com a redação padrão. Para alterar uma linha, remova o #, escreva o seu texto e guarde:

loginAccountTitle=Sign in to Acme
doLogIn=Sign in
doForgotPassword=I forgot my password

Adicione ficheiros como messages_fr.properties para francês ou messages_de.properties para alemão, depois ative esses idiomas na consola de administração em Realm settings > Localization.

Dica: O separador Localization também tem uma secção Realm overrides, que permite alterar textos diretamente na consola: não é necessário editar ficheiros nem reiniciar. Use o método que melhor se adapta ao seu fluxo de trabalho.

Personalizar os seus emails

O Keycloak envia emails para confirmação de endereço, redefinição de palavra-passe e convites de utilizador. Em default/email/messages/messages_en.properties, encontrará os assuntos e mensagens padrão prontos a personalizar:

emailVerificationSubject=Confirm your Acme account
passwordResetSubject=Reset your Acme password

Ao editar o corpo dos emails, tenha em atenção:

• Mantenha os placeholders {0}, {1}, {2} (o Keycloak irá preenchê-los com o link, nome de exibição e tempo limite).
• Para escapar apóstrofos, escreva dois (don''t).

Para substituir o HTML dos emails, copie o template pretendido do Keycloak base email theme para default/email/html/ e edite a sua cópia.

O Stackhero configura o envio de emails por si, com SPF, DKIM e DMARC já configurados. Configure-o em Realm settings > Email usando o host e a porta indicados na página do seu serviço.

Se precisar de repor o seu tema

Se algo correr mal, pode apagar todo o diretório default e reiniciar o serviço. O Stackhero irá criar um novo tema por defeito, restaurando a aparência padrão do Keycloak.

Os seus realms, utilizadores e clientes estão guardados na base de dados e não são afetados.

Desenhe o seu tema visualmente com o Quick Theme

Na consola de administração do Keycloak, encontrará o Quick Theme, o designer visual de temas do Keycloak. Carregue um logótipo, escolha as suas cores, pré-visualize as páginas de login e de conta, e descarregue o tema final como um ficheiro .jar.

Para instalar, coloque o ficheiro no diretório themes/ através do editor e reinicie o serviço. O .jar é extraído para um diretório de tema e o arquivo é removido:

themes/acme.jar        torna-se     themes/acme/

O novo tema aparecerá em Realm settings > Themes. Pode continuar a editar os ficheiros manualmente, se desejar.

Este método também suporta temas criados com Keycloakify ou fornecidos por um designer. Qualquer .jar ou .zip que contenha um tema pode ser instalado desta forma. Se já existir um tema com o mesmo nome, o novo será instalado como acme-1, garantindo que os seus envios nunca sobrescrevem o seu trabalho. Se o ficheiro não for um tema, é simplesmente ignorado e o Keycloak inicia normalmente.

Uma marca por realm: suporte white-label

Os temas são selecionados por realm em Realm settings > Themes, com opções para cada tipo de página: login, conta, admin e email. Cada aplicação pode também definir o seu próprio tema de login nas definições do cliente.

Se gere várias marcas ou oferece soluções white-label, utilize um realm por marca e atribua um tema personalizado a cada um:

1. No editor, copie o diretório default e renomeie a cópia (por exemplo, acme).
2. Reinicie o serviço.
3. Na consola de administração, abra o realm correspondente e selecione acme como tema de login.

Qualquer realm não configurado continuará a usar o seu tema default.

Compreender a estrutura de temas do Keycloak

Um tema é um diretório que contém subdiretórios para cada tipo de página:

themes/
  acme/
    login/                             # Páginas de autenticação do utilizador
      theme.properties                 # Herança do tema e inclusão de CSS
      resources/css/stackhero.css      # O seu CSS
      resources/img/logo.svg           # As suas imagens
      messages/messages_en.properties  # Os seus textos
    account/                           # Gestão de perfil do utilizador
    admin/                             # Aparência da consola de administração
    email/                             # Templates de email

Os temas são herdados dos temas padrão do Keycloak, sobrescrevendo apenas o necessário. Um ficheiro típico login/theme.properties é assim:

parent=keycloak.v2
styles=css/styles.css css/stackhero.css

• parent define o tema base.
• styles lista os ficheiros CSS a carregar. Coloque o seu CSS no fim para garantir que as suas alterações têm efeito.

A lista styles substitui a lista do tema pai, não a estende. Inclua sempre a folha de estilos do pai (css/styles.css) ou a sua página perderá o estilo padrão.

Só precisa de templates FreeMarker (.ftl) se quiser alterar a estrutura HTML. Para cores, logótipos, fundos, textos e idiomas, não é necessário editar templates. Para mais detalhes, consulte a documentação de temas do Keycloak.

Extensões Java (providers)

O diretório providers/ destina-se a funcionalidades que os temas não cobrem: authenticators personalizados, armazenamento de utilizadores, listeners de eventos ou protocol mappers.

Coloque o seu ficheiro .jar neste diretório e reinicie o serviço. Este reinício demora um pouco mais (cerca de um minuto), pois o Keycloak recompila-se para incluir a nova extensão. Para remover uma extensão, apague o ficheiro e reinicie novamente.

Também pode colocar ficheiros .jar de temas aqui, mas para temas recomenda-se usar themes/: não requer recompilação e permite editar os ficheiros posteriormente.