Customizing the look and feel

The look and feel of The Identity Hub can be customized on different levels:

global (cross tenant)
tenant specific

Next to this, views and partial views can also be localized.
Based on the level the files should be placed in a certain folder and/or follow a specific naming convention.
Files can be centralized either within the folder structure of The Identity Hub or on a file share.

For an example customization folder and files see https://github.com/TheIdentityHub/UI-Customizations

Note

The Identity Hub adds a CSP header which might prevent your customizations to show properly. You can optimize the CSP header to work with your customization, see CSP Header Custom Config

How to get started when customizing (partial) views

For the Identity Hub to apply customizations start by editing the web.config file and add an application setting UseOnPremiseCustomizations set to true.
Setup the correct folder structure

When putting the customizations within the deployed Identity Hub website: create a folder "Customizations" in the webroot.
When putting the customizations on a file share configure this location in the web.config with an application setting UseOnPremiseCustomizationsFileShare or UseOnPremiseCustomizationsAzureFileShare depending where you host The Identity Hub.

We will further refer to the created folder as the "Customizations root"

Within the Customizations root create the following structure for global (cross tenant) customizations which mimics the folder structure within the Areas and Views folder in the webroot
\Areas...
\Views...
In case you want tenant specific customizations grouped in a folder: create a folder which name is the same as the tenant segment and below copy the same folder structure as in step 3, so you will get:
{tenant}\Areas...
{tenant}\Views...

Tip

Use this type of configuration if multiple views are tenant specific or you have multiple tenants which require a custom layout.

Within every Views folder below the Customizations root put a web.config file with the content as specified in : Required web.config per customized Views folder
Copy the default (partial) view as provided by The Identity Hub in its corresponding customized folder location. Rename the file if needed as follows:

In case the file is localized suffix the filename to include the culture name (as supported by .NET) eg Index.nl.cshtml for the Dutch version of an Index.cshtml
In case the file is tenant specific but put in the cross tenant Customizations folder the file should be renamed to include the tenant segment as prefix. eg {tenant}.Index.cshtml

Adapt the view as wanted. Note that customizations should not break the default behavior of The Identity Hub.

Layout files

Warning

ASP.NET search locations are not applied to layout files, therefore The Identity Hub (version 1.37 and above) exposes its CustomizationViewEngine to allow you to customize layouts as well.

When you customize a view verify if it states its Layout.
If not, ASP.NET will by default pick up the Layout via the _ViewStart.cshtml file located at the Views folder level above the view file.
If needed also copy the _ViewStart.cshtml from the Views folder of The Identity Hub to your corresponding Views folder.

If wanted the layout files can also be customized by copying them to their corresponding location in your Customizations root.
The same naming conventions apply to make these files tenant specific.
Note that customizations should not break the default behavior of The Identity Hub.

Configuration overview

application setting	value
UseOnPremiseCustomizations	Must be configured to `true` for customizations to take effect
UseOnPremiseCustomizationsFileShare	To be used if the customized files are deployed eg on a central network share
UseOnPremiseCustomizationsAzureFileShare	To be used if the customized files are deployed on a central Azure File Share within your Azure Cloud
UseOnPremiseCustomizationsUseDefaultTenantCustomizations	Set this to `true` if cross tenant customizations can be applied if no tenant specific customizations are found. Set to `false` to not apply cross tenant customizations. The Identity Hub will fall back to the default out-of-the-box views when no tenant specific customizations are found.
TraceFileShareVirtualPathProvider	Can be set to `true` during troubleshooting when the customizations are in a (azure) file share and are not applied
CustomSiteCssFile	The name of the custom css file

Required web.config per customized Views folder
CSP Header Configuration