Keycloak: O seu tema está pronto a ser editado

Esta documentação faz parte do guia Personalizar a aparência. Consulte o guia completo aqui: 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.

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.