Branding PowerBI Report Server & SSRS 2017

Recently I was working on rolling out a new PowerBI Report Server, along with migrating our 2014-based SQL Server Reporting Server to a newer 2017-based system. One of the benefits of moving beyond 2014 (with SSRS) is that the appearance of the web portal (company logo & color scheme) can be customized (branded) using the same files that are used for branding PowerBI Report Server (PBIRS). While the customization process is easy to implement, figuring out which web portal elements were controlled by each configuration parameter (json key value) was a bit of a challenge. So here’s a quick run-down of the requirements for creating a branding package, along with some information & examples on how to customize each of the web elements in PBRIS (Sept. 2019 release) & SSRS (2017).


  1. SQL Server 2012 Enterprise Edition (or newer)
  2. Software Assurance or PowerBI Premium Subscription (for PowerBI Report Server)
  3. .NET Framework 4.6
  4. Windows Server 2012 x64 or newer

Installation Considerations:

Beginning with 2016, SSRS is a downloadable installer (instead of being incorporated in the SQL Server media as with earlier versions). The license key for both SSRS & PBRIS can be found either in the SQL Server installation media, on the Microsoft Volume License web portal, or on the Premium settings tab of the Power BI admin portal (depending on how the license was purchased). Both products can also be installed on servers separate from the SQL Server instance that hosts their databases. A new PBRIS installation can use (ie upgrade/convert) an existing SSRS database, but both SSRS & PBRIS cannot share the same database. If PBRIS and SSRS are installed on the same server, one of them must be configured to use ports other than 80 & 443 (http and https).

Branding The Web Portal:

By default, both applications have similar layouts.

Clicking on the Branding menu in Site Settings will bring up the interface for uploading the customized branding package (zip file).

The zip file can contain 3 files:

  • An optional logo file (png format)
  • metadata.xml
  • colors.json

Logo file

The optional logo file will replace the PowerBI logo & text specified in the Site Settings – General – Properties – Name field. The logo file must be in PNG format and the file name shouldn’t contain any special characters (ie. spaces, dash/hyphens, etc.). The logo will be scaled to about 290 x 60 pixels.

Default Logo Example Logo Example


The metadata.xml file contains the name and version information of the branding package, along with the names of the logo and color config files.

<?xml version="1.0" encoding="utf-8"?>
<SystemResourcePackage xmlns=""
  name="Example brand with logo"
    <Item key="colors" path="colors.json" />
    <Item key="logo" path="logo.png" />


The colors.json file contains the hex color values for the various elements of the web interface. The json keys are separated into 2 main sections: Interface and Theme. The Interface keys relate to the web portal, and the Theme keys are for mobile reports. Within the Interface section, the keys are broken down into several categories (Primary, Secondary, neutralPrimary, neutralSecondary, neutralTertiary, Report Messages & KPIs).

Interface – Primary (Buttons & Hover)

Key NameDescription
PrimaryButton background
PrimaryAltButton background (Hover)
PrimaryAlt2Title Bar Hover
PrimaryAlt3Active Tab Background
PrimaryAlt4Breadcrumb Links Text Color
PrimaryContrastButton Foreground (Text)
(eg. File, View, Edit in PowerBI Desktop)

Interface – Secondary (left-side menu, title & search bars)

Key NameDescription
SecondaryTitle Bar
SecondaryAltSearch Bar Background & Left-side Menu Background
SecondaryAlt2Search Bar Button Hover & Inactive Search Bar Button Foreground (Text)
SecondaryAlt3??? unknown
SecondaryContrastTitle and Search Bar Foreground (Text) & Left-side Menu Active Foreground (Text)

Interface – NeutralPrimary

Key NameDescription
neutralPrimaryHome Bar Background & Tile Background
neutralPrimaryAltPage Background & Report Bars Background
neutralPrimaryAlt2Search Bar Dividing Line
neutralPrimaryAlt3List Lines
neutralPrimaryContrastHome Bar Foreground (Text) & List and Tile Foreground (Text) & Active Tile Outline

Interface – NeutralSecondary

Key NameDescription
neutralSecondaryText Box Background & Title Menu Background & Page Loading Background
neutralSecondaryAltDrop-down Menu Dividing Lines & Pop-up Menu Dividing Lines
neutralSecondaryAlt2Text Box Border
neutralSecondaryAlt3Button Background (Hover)
neutralSecondaryContrastText Box Foreground (Text Color) & Drop-down Menu Foreground (Text Color) & Pop-up Menu Foreground (Text Color)

Interface – NeutralTertiary

Key NameDescription
neutralTertiaryBreadcrumb Indicator
neutralTertiaryAltLeft-side Menu Foreground (Text) & Apply Button & Cancel Button Hover & Subscription Toolbar Dividing Line
neutralTertiaryAlt2Pop-up Menu Hover & Properties/Settings/Subscription Background
neutralTertiaryAlt3Settings Toolbar Hover & Download/Remove Button Background
neutralTertiaryContrastSettings & Subscription Page Foreground (Text)

Report Messages – The following keys allow for customizing the text and background colors of their respective report message types.

Key NameDescription
dangermessage background
success message background
warning message background
info message background
successContrast text/foreground
warningContrast text/foreground
infoContrast text/foreground


Key NameDescription
kpiGoodGood KPI Background
kpiBadBad KPI Background
kpiNeutralNeutral KPI Background
kpiNoneNone KPI Background
kpiGoodContrastGood KPI Foreground (Text)
kpiBadContrastBad KPI Foreground (Text)
kpiNeutralContrastNeutral KPI Foreground
kpiNoneContrastNone KPI Foreground (Text & Graphics)

Theme (Mobile Report Visualizations) – These keys will be used to create a custom for mobile reports. The theme will appear in the server’s list of available themes (upper-right menu) in the Mobile Report Builder.

20 thoughts on “Branding PowerBI Report Server & SSRS 2017”

    1. Not that I know of. The System Resource Package link doesn’t appear to have any effect on the branding package. The critical parts are the Item Key entries for color and logo file paths.

      1. hi Jamie,
        I did these steps

        1) add files colors.json, logo.png and metadata.xml into zip file

        2) make change https to http in metadata.xml

        2) also confirm the name MSSQLTIPS in colors.json file
        3) press button Upload brand package for upload the zip file
        4) I pop the error “given key was not present in the dictionary”
        5) that is why I found the schema is not present in given link

      2. hi Jamie,
        I tried again for only colors.json it works
        but when i get logo file it gives me the error
        is there any size issue ?
        if so then what size should I provide?

        1. The logo file is scaled to around 290×60. The one I use is 1150×500 native and 40kb. Also, maybe try changing the filename to something other than logo.png. I think that name might be reserved for the default settings.

          1. OK, I have issue due to logo.PNG. it works after rename this file to logo.png. There may be case sensitive issue.

            but now if I set optional logo the original name given get replaced as you mentioned above.

            is there any way to provide the logo and company name there except only logo?
            I want keep the name as is

  1. Maybe in a future update/version. For now the only option is to have text or an image file in the title/name area.

  2. neutralTertiaryAlt is not the correct JSON for the Left-side unselected Menu items Foreground (Text.
    I’ve been searching for what it is and cannot find it. Any help would be appreciated.

    1. Robert,

      I just tried modifying the neutralTertiaryAlt on one of my servers. After changing the value to red (#FC0339) and applying the modified json, the text color for the unselected Site Settings menu items turned to red.

      1. Very weird. That did not work for me. On the Schedules screen, it changed the color of the lines around New Schedule, Enable, Disable, etc. I followed your steps exactly. I can’t figure out how to post the screenshot here to show you.

        1. Robert –
          I just tried the same settings on an SSRS 2019 server, with the same results. Are you by chance using an earlier (2016?) version of SSRS?

          1. SQL Server 2017 reporting Services – Version 14.0.600.906 (October 2017)

  3. Thank you for the article. It’s been super helpful for me. I can’t find the right json setting for the text that is in the toolbar below the breadcrumbs (when a report is being viewed). The text is ‘File’, “view’, ‘Edit in Power BI Desktop’, etc. I’ve tried setting neutralSecondaryContrast and neutralTertiaryContrast to #fff but the text is still a black-ish color that i can’t pinpoint. Any thoughts?

      1. Hi Jamie. Changing the value of ‘primaryContrast’ had no impact. I used the value of #ffoooo, but there was no red text anywhere on the site. We are using Power BI RS v1.10.7698.27886 (Jan 2021)

        1. Tom –
          I’m running the same version of PBIRS and have the same problem when using FF0000 for primaryContrast. However, when I used FF000C, the [File],[View], etc are a shade of red. Can’t explain why one color works and the other doesn’t….

          1. You totally nailed it – thank you for the tip! i altered my red hex code a bit as you suggested, and the text color was mostly red, as expected. So i then applied the color i really wanted – #ffffff – but then the text ended up back at some color close to black. That’s when i applied you trick – i set the color to #fffffd – and now i have the desired ‘white-ish’ color i was after. Seems like a bug with their less parser ? anyway, thanks for your help.

Leave a Reply

Your email address will not be published. Required fields are marked *