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:

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 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.

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.

"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 site. This site lets you upload a config.json file that makes it easier to create a customized Bootstrap file. The ForgeRock 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:

...
"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:

Shut down the IDM instance.
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
```
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:
```
{
    "enabled" : true,
    "cacheEnabled" : true,
    "urlContextRoot" : "/",
    "defaultDir" : "&{idm.install.dir}/ui/admin/default",
    "extensionDir" : "&{idm.install.dir}/ui/admin/extension",
    "responseHeaders" : {
        "X-Frame-Options" : "DENY"
    }
}
```
Restart the server.
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 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

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:

"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.

PingIDM 7.5.0