> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/getting-started-guide/brand-the-portals.md).
# Brand the portals
Apply your own CSS to the OpenIAM login, Webconsole, and SelfService portals.
**Goal:** your logo, colors, and styling on the login page and portals — built with a method that works, not by trial and error.\
**Time:** 60–90 minutes for a first working brand.\
**Prerequisites:** a running stack with Webconsole access. Basic CSS familiarity helps; the method below supplies the OpenIAM-specific knowledge.
## How OpenIAM branding actually works (read this first)
Three facts explain every branding success and failure:
1. **It's an override, not an edit.** OpenIAM's static UI app serves assets from two places, custom folder first: anything you put under `/data/openiam/conf/ui/static/custom/` overrides the packaged asset at the same relative path — CSS, images, fonts, JavaScript alike. You never modify shipped files.
2. **Your stylesheet loads last.** A UI theme's *Stylesheet URL* is appended after all default CSS on every page, so your rules win whenever they match at equal or higher specificity.
3. **Static assets are cached for 5 days.** The single most common "my CSS doesn't work" is cache. Always verify with `Ctrl+F5` or an incognito window. (Upgrades cache-bust automatically via a version query string like `custom.css?2026.7.1`.)
Two things are *not* done with CSS: **footer/copyright text** (Administration → System Configuration → UI tab → Footer) and **application tile icons** in the Launchpad (set per application on its Authentication Provider's *Application Icon* field).
{% stepper %}
{% step %}
**Get the pipeline working before you style anything**
Prove the override chain with a deliberately ugly smoke test.
{% code overflow="wrap" %}
```bash
sudo mkdir -p /data/openiam/conf/ui/static/custom/bootstrap-ui/css
sudo mkdir -p /data/openiam/conf/ui/static/custom/images
cat <<'EOF' | sudo tee /data/openiam/conf/ui/static/custom/bootstrap-ui/css/custom.css
/* smoke test — remove after step 1 */
body { background: #ff00ff !important; }
EOF
sudo chown -R openiam:openiam /data/openiam
sudo systemctl restart openiam-ui-static
```
{% endcode %}
The file **must** be named `custom.css`. Then wire it up in the Webconsole:
1. **Administration → UI Themes** → edit the existing theme (or create one) → set *Stylesheet URL* to `/openiam-ui-static/bootstrap-ui/css/custom.css` → Save.
The same screen carries the image uploads. Sizes are recommendations, not limits — but matching them avoids the browser rescaling your logo:
| Upload | Recommended size | Where it appears |
| -------------------------------- | ---------------- | ---------------------------------------------- |
| Login and self-registration logo | 270 × 100 | The sign-in and self-registration pages |
| Application logo | 110 × 40 | The top-left of the Webconsole and SelfService |
| Favicon | 16 × 16 | The browser tab |
**Upload only the largest favicon you have.** OpenIAM replicates it to every size the browsers ask for, so there is no need to prepare a set.
2. **Access Control → Content Providers** → your content provider (from [Verify health and log in](/getting-started-guide/verify-and-first-login.md)) → select the theme in *UI Theme* → Save. All URL patterns inherit it unless a pattern sets its own theme — which is also how you can brand `/selfservice/*` differently from `/webconsole/*` later.
3. Hard-reload the login page (`Ctrl+F5`).
If the page is now violently magenta, your pipeline works — everything from here is just CSS. Remove the smoke-test rule.
{% endstep %}
{% step %}
**Learn the selectors from the page itself, not from guesswork**
The reliable method for building working rules:
1. Open the page you want to change (start with the login page) in Chrome/Edge/Firefox.
2. Press `F12`, use the element picker (`Ctrl+Shift+C`), and click the element — logo, button, background.
3. Read the class/ID in the inspector (e.g. the login logo is `` inside `
