--- title: Customize the admin UI description: This section shows you how to customize the admin UI for your deployment. component: pingidm version: 8 page_id: pingidm:setup-guide:ui-customizing-admin canonical_url: https://docs.pingidentity.com/pingidm/8/setup-guide/ui-customizing-admin.html keywords: ["Setup & Configuration", "User Interface", "Customization"] section_ids: ui-admin-customizing-directories: Default UI subdirectories ui-bootstrap: Customize the UI theme ui-logo: Change the default logo ui-project-config: Create project-specific themes custom-response-headers: Set custom response headers ui-disabling: Disable the admin and end-user UIs ui-enable-auth: Protect custom static web resources ui-enable-cache: Cache static UI files in memory --- # Customize the admin UI This section shows you how to customize the admin UI for your deployment. The default admin UI configuration files are located in `openidm/ui/admin/default`. To customize the UI, copy this directory to `openidm/ui/admin/extension`: ```bash cd /path/to/openidm/ui/admin cp -r default/. extension ``` You can now edit the custom files in the `extension` subdirectory. The admin UI templates in `openidm/ui/admin/default/templates` can help you get started. ## Default UI subdirectories The admin UI config files are located in separate subdirectories: * `config/` Top-level configuration directory of JavaScript files. Customizable subdirectories include `errorhandlers/` with HTTP error messages and `messages/` with info and error messages. For actual messages, refer to the `translation.json` file in the `locales/en/` subdirectory. * `css/` and `libs/` If you use a different [bootstrap](#ui-bootstrap) theme, replace the files in these directories and subdirectories. * `fonts/` The font files in this directory are based on the Font Awesome CSS toolkit. * `images/` and `img/` IDM uses the image files in these directories. You can replace these images with your own. * `locales/` The `translation.json` file (in the `en/` subdirectory by default) contains the UI labels and messages. * `org/` Source files for the admin UI. * `partials/` Includes partial components of HTML pages in the admin UI, for assignments, authentication, connectors, dashboards, email, basic forms, login buttons, and so on. * `templates/` The HTML templates for various UI pages. Note that these files are used by the UI. Do not change the template files in `ui/admin/default/`. ## Customize the UI theme You can configure a few features of the UI in the `ui-themeconfig.json` file in your project's `conf` directory. However, to change most theme-related features of the UI, you must copy target files to the appropriate `extension` subdirectory, and then modify them as discussed in [Customize the admin UI](ui-customizing-admin.html). By default, the UI reads the stylesheets and images from the `openidm/ui/admin/default` directory. Do not modify the files in this directory. Your changes may be overwritten the next time you update or even patch your system. To customize your UI, first set up matching subdirectories in (`openidm/ui/admin/extension`). For example, `openidm/ui/admin/extension/libs` and `openidm/ui/admin/extension/css`. You might also need to update the `"stylesheets"` listing in the `ui-themeconfig.json` file for your project, in the `project-dir/conf` directory. ```json "stylesheets" : [ "css/bootstrap-3.4.1-custom.css", "css/structure.css", "css/theme.css" ], ``` The default stylesheets contain: * `bootstrap-3.4.1-custom.css`—Includes custom settings that you can get from various Bootstrap configuration sites, such as the Bootstrap [Customize and Download](https://getbootstrap.com/customize/) site. This site lets you upload a `config.json` file that makes it easier to create a customized Bootstrap file. The Ping version of this file is in `ui/admin/default/css/common/structure/` . You can use this file as a starting point for your customization. * `structure.css`—For configuring structural elements of the UI. * `theme.css`—Includes customizable options for UI themes such as colors, buttons, and navigation bars. To set up custom versions of these files, copy them to the `extension/css` subdirectories. ## Change the default logo The default UI logo is in `openidm/ui/admin/default/images`. To change the logo, place your custom image in the `openidm/ui/admin/extension/images` directory. You should see the changes after refreshing your browser. To specify a different file name, or to control the size, and other properties of the logo image file, adjust the `logo` property in the UI theme configuration file for your project `(conf/ui-themeconfig.json)`. The following change to the UI theme configuration file points to an image file named `example-logo.png`, in the `openidm/ui/admin/extension/images` directory: ```json ... "loginLogo" : { "src" : "images/example-logo.png", "title" : "Example.com", "alt" : "Example.com", "height" : "104px", "width" : "210px" }, ... ``` Refresh your browser window for the new logo to appear. ## Create project-specific themes You can create different UI themes for projects and then point a particular UI instance to a defined theme on startup. To create a complete custom theme, follow these steps: 1. Shut down the IDM instance. 2. Copy the entire default admin UI theme to an accessible location. For example: ``` cp -r /path/to/openidm/ui/admin/default /path/to/openidm/admin-project-theme ``` 3. In the copied theme, modify the required elements, as described in the previous sections. Note that nothing is copied to the extension folder in this case—changes are made in the copied theme. In the `conf/ui.context-admin.json` file, modify the values for `defaultDir` and `extensionDir` to the directory with your `new-project-theme`: ```json { "enabled" : true, "cacheEnabled" : true, "urlContextRoot" : "/", "defaultDir" : "&{idm.install.dir}/ui/admin/default", "extensionDir" : "&{idm.install.dir}/ui/admin/extension", "responseHeaders" : { "X-Frame-Options" : "DENY" } } ``` 4. Restart the server. 5. Relaunch the UI in your browser. The UI displays with the new custom theme. ## Set custom response headers You can specify custom response headers for your UI by using the `responseHeaders` property in UI context configuration files such as `conf/ui.context-admin.json`. For example, the `X-Frame-Options` header is a security measure used to prevent a web page from being embedded within the frame of another page. For more information about response headers, refer to the [MDN page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) on HTTP Headers. Because the `responseHeaders` property is specified in the configuration file for each UI context, you can set different custom headers for different UIs. For example, you might set different security headers included for the admin and end-user UIs. ## Disable the admin and end-user UIs | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | In PingIDM 8.0, the end-user UI is not bundled with PingIDM. You can download and install the end-user UI separately by going to the [ForgeRock/end-user-ui](http://github.com/ForgeRock/end-user-ui) GitHub repository and following the guidance in the [End-User UI README Quick start](https://github.com/ForgeRock/end-user-ui?tab=readme-ov-file#quick-start). Learn more in [Incompatible changes](../release-notes/changed-functionality.html) and [End-user UI limitations](../release-notes/limitations.html#limitations-end-user-ui). | The UIs are packaged as separate bundles that can be disabled in the configuration before server startup. To disable the registration of the UI servlets, edit the `project-dir/conf/ui.context-ui.json` files, setting the `enabled` property to false. For example, to disable the end-user UI, set `"enabled" : false,` in `project-dir/conf/ui.context-enduser.json` ## Protect custom static web resources By default, custom static web resources are publicly accessible. To require authentication to access these resources, add the following line to the applicable `project-dir/conf/ui.context-ui.json` files: ```json "authEnabled" : true, ``` ## Cache static UI files in memory By default, static UI files are cached in memory for all but the API Explorer. To disable the caching of specific UI files, set `"cacheEnabled": false` in the applicable `project-dir/conf/ui.context-ui.json` file. When caching is enabled, all static files are cached in-memory, but off-heap, when they are first accessed. When caching is disabled, the files are streamed from disk. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | UI asset directories that contain large files should not enable caching. You can reduce RAM usage by disabling caching where it is not required. |