Branding

Match your product's branding

Your app already has a design system, and the redirect to Keycloak should feel like part of it, not a jarring context switch.

1. Choose Bootstrap or Carbon if your product is built on one of those; otherwise start from v2.
2. Choose Card for a compact form, or Split for a wider, more branded screen. Recheck the mobile preview after switching.
3. Upload your logo and fonts, and set the primary color and background. Uploaded assets keep the login working even if your normal asset host is unreachable.
4. Add privacy or imprint links if your theme supports them, and check where they point.
5. Step through login, registration, password reset, OTP, and an error state. Use a long product name and a translated label to check wrapping.
6. Export under a stable theme ID (e.g. acme-login) and deploy to staging.

You're done when someone can go through your actual app, trigger an invalid-password error, reset a password, and complete MFA, all with the new branding. Keep the theme ID stable across releases; version the artifact instead, e.g. acme-login-1.2.0.jar.

Give each customer portal its own branding

Running several customer-facing portals and want some, or all, of them branded individually? First figure out how Keycloak already distinguishes them:

Your setup	Where to assign the theme
Each customer has its own realm	Set the login theme on that realm.
Portals are separate clients in one realm	Set a login theme per client.
Customers share a single client	The editor can't select themes by tenant or hostname: solve that in your app or Keycloak setup first.

Realm and client theme assignment both live in Keycloak's admin console; see the Server Administration Guide if you're not familiar with it.

To create a variant for one customer:

1. Import your saved acme-login export.
2. Swap the logo, colors, background, and any customer-facing copy.
3. Export under a new theme ID, e.g. northwind-login.
4. Deploy both themes and point the right realm or client at each.
5. Sign in through each portal, and also test an expired session and a password-reset link.

Keep a short inventory of what's assigned where:

Portal                       Realm       Client          Login theme
app.acme.example             customers   acme-web        acme-login
portal.northwind.example     customers   northwind-web   northwind-login

A copied theme is independent afterward: a shared fix has to be applied, and tested, in every variant separately.

Handing a design off to engineering

Include with the change request:

• The exported JAR and its theme ID.
• Screenshots of login, an error state, and a narrow viewport, in every color mode you support.
• The Keycloak version you checked it against in staging.
• Which realms or clients it affects, and a short summary of what changed.

Engineering imports the JAR to inspect it, runs the staging checks, and promotes the reviewed artifact. If a designer and an engineer are both actively iterating on the same theme, share local theme files in Git instead of passing exports back and forth: a browser session isn't something you can hand off.