> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/config/login-page.md).

# Branding

Customize PowerShell Universal branding with examples for login pages, logos, colors, stylesheets, portal titles, and error messages.

{% hint style="info" %}
Branding customization requires a [license](https://store.devolutions.net/package#psu).
{% endhint %}

Branding controls the appearance and text of PowerShell Universal's built-in login page, admin console, portal, and selected error pages. Use **Settings > Branding** or the `.universal\branding.ps1` file in your configuration repository. Refresh the browser after saving; some images, styles, and titles are loaded when the page opens.

Branding is not an app-wide Material UI theme. To style the components inside an app, use [app themes](/powershell-universal/apps/themes.md).

## Choose how to configure branding

In **Settings > Branding**, use the **Text**, **Colors**, **Images**, and **Login Page** tabs, then select **Save**. The tables below use PowerShell parameter names so you can map each example to the corresponding setting. Updating branding requires `settings.branding/update` permission.

For configuration as code, keep one branding definition in `.universal\branding.ps1`. `New-PSUBranding` and `New-PSULoginPage` are aliases of `Set-PSUBranding`. In a configuration file, they produce the branding object that PSU loads. Outside configuration loading, the cmdlet applies the object to the connected server and returns it.

{% hint style="warning" %}
A branding cmdlet call replaces the branding definition; it does not merge only the parameters supplied. Omitted strings return to their defaults, and omitted theme and layout values become `System` and `Vertical`. Keep your desired settings together in one definition. The examples below extend the same `$branding` hashtable so later changes do not erase earlier values.
{% endhint %}

If running the examples interactively, first connect to the intended server with `Connect-PSUServer`. Do not run successive examples against an existing deployment without including the settings you want to preserve.

## Host images and CSS files

Image and stylesheet settings take browser-accessible URLs, not server filesystem paths. For example, `C:\PSU\Branding\logo.png` is a local file, while `/branding/logo.png` is the URL the browser can request.

1. Create a dedicated folder, such as `C:\PSU\Branding`, on the PSU server. Give the PSU service account read access.
2. Place your public branding files in that folder: `logo.png`, `logo-on-dark.png`, `favicon.ico`, and, if needed, `login.css`.
3. Publish the folder at `/branding`. Leave authentication and role restrictions disabled so the login page can load these assets before a user signs in.

For example, place this definition in `.universal\publishedFolders.ps1`:

```powershell
New-PSUPublishedFolder -Name 'BrandingAssets' -Path 'C:\PSU\Branding' -RequestPath '/branding'
```

Only put public images and stylesheets in this folder. Everything it serves is accessible without signing in; do not publish your configuration repository, scripts, credentials, or other private files. The filesystem path can be outside the configuration repository. On other operating systems, use an appropriate local path.

Open `/branding/logo.png` and `/branding/login.css` on your PSU site in a private browser window to confirm anonymous access. See [Published Folders](/powershell-universal/platform/published-folders.md) for more details.

The examples assume PSU is hosted at the site root. If it runs under a virtual directory or proxy path prefix, include that prefix in the URLs, or use full HTTPS URLs reachable by your users' browsers. Do not use a `localhost` URL unless every browser is running on the server itself.

## Example: a branded login page and console

After publishing the assets, put this in `.universal\branding.ps1`:

```powershell
$branding = @{
    AdminConsoleTitle    = 'Contoso Automation'
    PortalTitle          = 'Contoso Self-Service'
    LoginPageTitle       = 'Contoso Automation'
    LoginPageText        = 'Sign in with your work account'
    LoginPageDescription = 'Automation and self-service for Contoso employees.'
    LoginPageImage       = '/branding/logo.png'
    LoginPageLogoSize    = '180px'
    AppBarLogo           = '/branding/logo.png'
    DarkAppBarLogo       = '/branding/logo-on-dark.png'
    Favicon              = '/branding/favicon.ico'
    Copyright            = 'Copyright 2026 Contoso'
    LoginPageTheme       = 'Light'
    LoginPageLayout      = 'Vertical'
}

Set-PSUBranding @branding
```

The login page displays the custom logo, description, and sign-in heading. `LoginPageTitle` also supplies the title suffix in the browser tab. In the current login layout, the visible custom title below the logo is rendered when a custom `LoginPageImage` is provided. `AdminConsoleTitle` supplies the admin console's browser-title suffix; a developer license uses the development title instead.

`AppBarLogo` supplies the built-in console and portal navigation logo. `DarkAppBarLogo` is the alternate image when their dark theme is active, not a request to darken the original image. Set both logo URLs. Choose a light-on-dark image for the alternate logo. This setting does not select a different login-page image: `LoginPageImage` is shared by both login themes.

| Parameter              | What to supply                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| `LoginPageTitle`       | Login page title, for example `Contoso Automation`. Alias: `Title`.                        |
| `LoginPageText`        | Heading inside the sign-in card, for example `Sign in with your work account`.             |
| `LoginPageDescription` | Text near the logo, for example a short audience or service description.                   |
| `LoginPageImage`       | URL of the login logo, for example `/branding/logo.png`. Alias: `Image`.                   |
| `LoginPageLogoSize`    | A CSS width, such as `180px`, `12rem`, or `50%`. The default custom-logo width is `128px`. |
| `AppBarLogo`           | URL of the regular console and portal logo.                                                |
| `DarkAppBarLogo`       | URL of the alternate navigation logo used in dark theme.                                   |
| `Favicon`              | URL of the browser-tab icon, for example `/branding/favicon.ico`.                          |
| `AdminConsoleTitle`    | Admin console browser-title suffix.                                                        |
| `PortalTitle`          | Title used by the portal's resource search and script pages.                               |
| `Copyright`            | Copyright text on the login page and wherever the built-in footer is rendered.             |

## Example: layout, theme, and login colors

To place the logo and description beside the sign-in card, change the profile to `Horizontal`. `Vertical` stacks the branding above the card. The horizontal layout can stack on narrow screens.

```powershell
$branding.LoginPageLayout = 'Horizontal'
$branding.LoginPageTheme = 'Light'
$branding.LoginPageBackgroundColor = '#E8F0F8'
$branding.LoginPageFontColor = '#172B4D'

Set-PSUBranding @branding
```

These lines assume `$branding` from the preceding example is still defined. For a configuration file, add the assignments before its single final `Set-PSUBranding @branding` call rather than adding a second branding definition.

| Parameter                  | Values and effect                                                                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LoginPageLayout`          | `Vertical` (default) or `Horizontal`.                                                                                                                                                   |
| `LoginPageTheme`           | `System` (default), `Light`, or `Dark`. Use `System`, not `Auto`. System mode considers the browser's saved PSU theme preference and otherwise the operating system's color preference. |
| `LoginPageBackgroundColor` | CSS color used for the login layout background and primary sign-in button background and border. It does not remove a built-in background image or change button text color.            |
| `LoginPageFontColor`       | CSS color applied to login-page typography. It is not a separate button-label or input-text color setting.                                                                              |

Use readable foreground/background combinations, and check the logo, description, buttons, and error messages in the themes your users use. `LoginPageTheme` controls the login page, not users' console theme preferences.

## Example: navigation and card colors

Extend the same profile with these values:

```powershell
$branding.SecondaryColor = '#16324F'
$branding.SecondaryFontColor = '#FFFFFF'
$branding.PrimaryColor = '#FFFFFF'
$branding.PrimaryFontColor = '#172B4D'

Set-PSUBranding @branding
```

The secondary colors target the built-in admin and portal navigation. The primary color pair is used by built-in cards such as the reset-password card; it is not the Material UI primary palette for apps, and it does not recolor every console control. Set `PrimaryColor` with `PrimaryFontColor` because these card overrides are applied together.

| Parameter                        | Scope                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `SecondaryColor`                 | Navigation/sidebar background.                                                                           |
| `SecondaryFontColor`             | Navigation's inherited foreground color; component styles can provide more specific colors.              |
| `PrimaryColor`                   | Background of built-in cards that consume the primary branding color.                                    |
| `PrimaryFontColor`               | Foreground paired with `PrimaryColor` on those cards.                                                    |
| `HeaderColor`, `HeaderFontColor` | Compatibility settings for older header layouts. The current console layout does not apply these values. |

## Example: customize the login stylesheet

Use `LoginPageCssStylesheet` when the built-in login settings are not sufficient. For example, to replace the built-in background image with a solid color and set an independent button color, save the following as `C:\PSU\Branding\login.css`:

```css
html body .ant-layout {
    background-image: none !important;
    background-color: #E8F0F8 !important;
}

html body .ant-btn-primary {
    background-color: #0066B0 !important;
    border-color: #0066B0 !important;
    color: #FFFFFF !important;
}
```

Reference the published URL in the same branding profile:

```powershell
$branding.LoginPageCssStylesheet = '/branding/login.css'
Set-PSUBranding @branding
```

This stylesheet is loaded on the login and login-error pages. It does not globally style the admin console or your apps. The example uses more specific selectors and `!important` to override built-in login styles. CSS selectors are implementation details: recheck custom styles after upgrading PSU.

Use only trusted stylesheets served over HTTPS or from your own PSU instance. If a change does not appear, inspect the stylesheet request in the browser's developer tools, then refresh without the cache. A versioned URL such as `/branding/login.css?v=2` can help when deploying an updated file.

## Example: friendly error and logout messages

Add these entries to the profile before applying it:

```powershell
$branding.PageNotFoundTitle = 'Page not found'
$branding.PageNotFoundDescription = 'Check the address or return to the home page.'
$branding.NotAuthorizedTitle = 'Access required'
$branding.NotAuthorizedDescription = 'Contact the service desk to request access.'
$branding.AppNotRunningDescription = 'This service is temporarily unavailable. Please try again later.'
$branding.LoggedOut = 'You are signed out'
$branding.LoggedOutDescription = 'Close your browser if you are using a shared computer.'

Set-PSUBranding @branding
```

| Parameter                                        | Where it is used                                                                                                  |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `PageNotFoundTitle`, `PageNotFoundDescription`   | Built-in page-not-found screen.                                                                                   |
| `NotAuthorizedTitle`, `NotAuthorizedDescription` | Built-in unauthorized screen.                                                                                     |
| `AppNotRunningDescription`                       | App framework screen shown when an app is not running. This is separate from the server's startup/loading screen. |
| `LoggedOut`, `LoggedOutDescription`              | Title and description on the built-in `/loggedout` screen.                                                        |

These settings change presentation, not access rules. They do not grant permissions, enable authentication providers, start an app, or change HTTP error handling in a reverse proxy. Keep messages free of secrets and internal diagnostic information.

## Compatibility parameters

The cmdlet reference includes parameters retained in the branding model that are not consumed by the current built-in page layouts:

| Parameter                        | Compatibility behavior                                                                                                                                         |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LoginPageLinks`                 | Accepts `LoginPageLink` objects, but the current vertical and horizontal login templates do not render them.                                                   |
| `CssStylesheet`                  | Accepts an array of stylesheet URLs, but the current admin console does not load these as global stylesheets. Use `LoginPageCssStylesheet` for the login page. |
| `CssStylesheetIntegrity`         | Companion integrity values for `CssStylesheet`; this does not add an integrity attribute to `LoginPageCssStylesheet`.                                          |
| `HeaderColor`, `HeaderFontColor` | Stored for compatibility; the current navigation-based console layout does not render the older branded header.                                                |

Rendering depends on the PSU version and page layout. A parameter being accepted and saved is not proof that a visible element uses it. Check the relevant page rather than adding more settings to compensate for an unused parameter.

## Reset and troubleshoot

To reset branding, select **Reset** on **Settings > Branding** and confirm. This replaces the saved definition with defaults. The equivalent interactive cmdlet call is:

```powershell
Set-PSUBranding
```

If configuration is managed through Git or another deployment process, update that source as well so it does not reapply the old branding. Resetting branding does not delete published image or stylesheet files.

| Symptom                                          | What to check                                                                                                                                                                 |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Logo or CSS does not load before login           | Open the exact URL in a private browser window. Check the published folder path, service account read access, and that the asset is not protected by authentication or roles. |
| Browser requests the wrong site or path          | Image settings must be URLs, not filesystem paths. Include any hosting path prefix. An HTTPS login page must not depend on HTTP assets.                                       |
| Earlier settings disappear after another example | Include all desired settings in one hashtable/branding definition; cmdlet calls replace the definition.                                                                       |
| Background color changes but the pattern remains | The color setting does not remove the background image. Use the stylesheet example if you want a solid background.                                                            |
| Theme value is rejected                          | Use `System`, `Light`, or `Dark`, not `Auto`.                                                                                                                                 |
| A valid setting has no visible effect            | Check the setting's scope and compatibility notes, refresh the browser, and verify that the intended configuration was loaded.                                                |
| Favicon or stylesheet still looks unchanged      | Check the network response and browser cache; use a versioned asset URL if needed.                                                                                            |

## API

* [Set-PSUBranding](/powershell-universal/powershell-commands/set-psubranding.md)
* [New-PSUBranding](/powershell-universal/powershell-commands/new-psubranding.md) (alias)
* [New-PSUPublishedFolder](/powershell-universal/powershell-commands/new-psupublishedfolder.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/powershell-universal/config/login-page.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.