Customize Your Library Login Page

Use the following steps to brand the Strategy login page with a supported web plugin. Library owns the login form, authentication flow, accessibility behavior, and page structure.

Prerequisites

Use the following procedure to apply customer branding to the Library login page without modifying product files. The customization is deployed as a Library web plugin that contains a versioned manifest file and optional image or stylesheet assets.

  • Confirm that you can access the deployed Library installation and its plugins directory.

  • Prepared approved logo, favicon, and background assets.

  • Identify the Library application IDs that require application-specific branding.

  • Back up the existing plugin directory and manifest before making changes.

  • Test the customization in a non-production environment before deploying it to production.

    Do not copy, replace, or modify MultiModeLogin.jsp. Custom HTML, JavaScript, JSP files, authentication forms, redirects, arbitrary message areas, and custom login logic are not supported.

What You Can Customize

See the following areas of the login experience you can customize:

  • Branding: Logo, favicon, and full-page background.

  • Layout: Panel background, width, height, border and corner radius.

  • Actions: Primary, hover, disabled, and text colors; button width and radius.

  • Typography: Font family, heading color, heading size and weight, and subtitle size.

  • Labels: Browser title, heading, subtitle, username, password, login, SAML, and OIDC labels.

  • Theme selection: One global default theme and application-specific themes selected by exact application ID.

  • Advanced CSS: One optional plugin-relative stylesheet. This is best effort and is not an upgrade compatibility contract.

Understand Theme Selection

Library resolves themes in the following order:

  1. Exact application match: If the request contains an application ID mapped to one valid theme, Library uses that theme.

  2. Global default: If there is no exact match and one valid global default exists, Library uses the default theme.

  3. Out-of-the-box behavior: If neither condition is met, Library uses the standard login page.

    An application-specific theme is complete by itself. Values missing from that theme use the standard Library behavior, they do not inherit values from the global default theme.

Customize Your Library Login Page

  1. Create a plugin directory as a direct child of the deployed Library plugins. For example, use the following:

    Copy 
    StrategyLoginCustomization/
    ├── README.md
    ├── WEB-INF/
    │   └── login-customization.json
    └── assets/
        ├── company-logo.png
        ├── company-favicon.png
        ├── company-background.jpg
        ├── operations-logo.png
        ├── operations-favicon.png
        └── operations-background.jpg

  2. The resulting deployment path must be the following:

    Copy 
    <deployed-library>/plugins/<plugin-name>/WEB-INF/login-customization.json

  3. Note the following:

    • Keep the manifest in WEB-INF/login-customization.json.

    • Keep browser-loaded assets outside WEB-INF.

    • Use plugin-relative paths for all referenced resources.

    • Do not use absolute paths, path traversal, unsafe symlinks, or unsupported file extensions.

    • Keep each referenced resource at or below 20 MiB.

  4. Create a manifest file with the title WEB-INF/login-customization.json and use the following required root fields and theme definitions:

    Copy 
    {
      "type": "library-login-customization",
      "version": 1,
      "defaultTheme": "corporate-default",
      "themes": [
        {
          "id": "corporate-default",
          "assets": {
            "logo": "assets/company-logo.png",
            "favicon": "assets/company-favicon.png",
            "background": "assets/company-background.jpg"
          },
          "tokens": {
            "primaryColor": "#286f73",
            "panelBackgroundColor": "#FFFFFF",
            "headingColor": "#172b4d",
            "panelWidth": "420px",
            "panelHeight": "560px",
            "panelBorderRadius": "12px",
            "logoWidth": "220px",
            "logoHeight": "64px",
            "pageBackgroundSize": "cover",
            "pageBackgroundPosition": "center center"
          },
          "strings": {
            "defaultLocale": "en-US",
            "locales": {
              "en-US": {
                "documentTitle": "Sign in",
                "heading": "Welcome",
                "subtitle": "Sign in to continue",
                "usernameLabel": "Username",
                "passwordLabel": "Password",
                "loginButton": "Log in",
                "samlButton": "Continue with SAML",
                "oidcButton": "Continue with OIDC"
              }
            }
          }
        },
        {
          "id": "operations",
          "applications": [
            "REPLACE_WITH_APPLICATION_ID"
          ],
          "assets": {
            "logo": "assets/operations-logo.png",
            "favicon": "assets/operations-favicon.png",
            "background": "assets/operations-background.jpg"
          },
          "tokens": {
            "primaryColor": "#0052CC"
          }
        }
      ]
    }

  5. Replace the sample values with the approved customer branding. The example application ID is intentionally a placeholder and must be replaced with the target Library application ID.

  6. Configure the following supported assets:

    Manifest Field Purpose Requirements
    logo Logo displayed in the login panel.

    Use a supported browser image format. Configure dimensions with logoWidth and logoHeight.
    favicon Icon displayed in the browser tab.

    PNG, JPG, SVG, and ICO are supported by the pre-authentication resource path.
    background Full-page login background. Use pageBackgroundSize and pageBackgroundPosition to control fitting and placement.

    Library generates a content fingerprint for each resource URL. Keep asset filenames stable. After replacing an asset, perform the normal plugin refresh or restart the procedure so Library publishes the new fingerprinted URL.

  7. Use the following supported token to configure common branding changes.

    Token Controls
    pageBackgroundColor Fallback page background color.
    panelBackgroundColor Login-panel background color.
    panelWidth, panelHeight Login-panel dimensions. Percentages are not supported for panel height.
    panelBorderColor, panelBorderWidth, panelBorderRadius Panel border appearance and corner radius.
    primaryColor, primaryHoverColor, primaryDisabledColor Primary actions and their interaction states.
    buttonTextColor, formButtonWidth, buttonBorderRadius Primary-action text, form-button width, and corner radius.
    headingColor, headingFontSize, headingFontWeight Heading appearance. Font weight must be from 100 through 900 in increments of 100.
    subtitleFontSize, fontFamily Subtitle size and browser-available font family.
    logoWidth, logoHeight Product-owned logo slot dimensions. Logo width supports percentages; logo height does not.
    pageBackgroundSize, pageBackgroundPosition Background fitting and placement.

    Values are validated by Library and invalid recognized values can cause the affected plugin to be ignored.

  8. Configure localized labels. Localized overrides are limited to documented labels already present on the Library login page. When a locale is requested, Library resolves each field independently using exact locale, language-only locale, the configured default locale, and then the standard Library value.

    The following fields are supported: documentTitle, heading, subtitle, usernameLabel, passwordLabel, loginButton, samlButton, and oidcButton.

    Note the following:

    • Omit a field to preserve the standard Library value.

    • Provide text to replace the existing value.

    • Use an empty string for subtitle if the subtitle should be hidden.

    • When strings is present, defaultLocale is required.

  9. Validate the following for the package:

    • Confirm the type value is library-login-customization.

    • Confirm the version value is 1.

    • Confirm themes is present and not empty.

    • Confirm that every theme ID is unique within the manifest.

    • Confirm that every application ID is correct and exactly matches the intended Library application.

    • Confirm that all asset paths are plugin-relative, exist, and remain outside WEB-INF.

    • Validate the JSON syntax and review all supported token values.

    • Confirm that no custom JSP, JavaScript, HTML, authentication form, redirect, or arbitrary message area has been added.

  10. Deploy the plugin:

    1. Stop or quiesce the deployment if required by the environment's normal plugin procedure.

    2. Copy the configured plugin directory into the deployed Library plugins directory.

    3. Confirm the manifest exists at <deployed-library>/plugins/<plugin-name>/WEB-INF/login-customization.json.

    4. Use the deployment's normal plugin-discovery refresh or restart procedure.

    5. Open the login page in a private browser deployments.

      The plugin is designed to support Library deployment models that use the standard web-plugin mechanism. Follow the deployment-specific installation and persistence procedure for your environment, especially for containerized deployments.

Verify the Results

Verify the presentation only. Do not submit credentials as part of this visual customization check.

Scenario URL Pattern Expected Result
Global default <Library URL>/auth/ui/loginPage The configured global default theme displays.
Exact application <Library URL>/auth/ui/loginPage?applicationId=<APPLICATION_ID>

The theme mapped to the exact application ID displays.
Unmatched application <Library URL>/auth/ui/loginPage?applicationId=<OTHER_ID> The global default theme appears when one valid default exists.
No valid customization

<Library URL>/auth/ui/loginPage

The standard Library login page appears.

Check the following items:

  • Correct logo, favicon, and background.

  • Panel dimensions, border, radius, and colors.

  • Primary, hover, disabled, and text colors.

  • Heading, subtitle, font, and label values.

  • Application-specific and default theme selection.

  • Locale fallback behavior.

  • Browser console and Library validation logs.

  • Asset updates after plugin refresh or restart.

Authentication submission is not required to verify the visual customization. Keep the authentication and form behavior owned by Library.

Rollback

  1. Follow the deployment change procedure.

  2. Remove or rename WEB-INF/login-customization.json within the plugin directory.

  3. Refresh or restart plugin discovery using the normal deployment procedure.

  4. Confirm that Library returns to the next valid resolution level, normally the standard login page.

Troubleshooting

Symptom Likely cause Action
Standard Library page appears Incorrect directory nesting, missing manifest, or invalid plugin. Confirm the direct-child plugin structure, manifest path, JSON syntax, and Library validation logs.
Default theme appears instead of the application theme The request application ID does not exactly match the configured ID. Check the application ID and login URL for exact spelling and casing.
Global default does not apply More than one installed plugin declares a valid default. Ensure only one valid plugin declares defaultTheme.
Application mapping does not apply More than one plugin owns the same application ID. Remove duplicate ownership. An ambiguous exact mapping is disabled.
Entire plugin is ignored Invalid value, duplicate ID, missing resource, unsafe path, unsupported extension, or oversized file. Validate the manifest and every referenced resource.
Updated asset does not appear Plugin registry or browser cache has not refreshed. Run the normal plugin refresh or restart procedure, then reload the page in a private browser session.
Custom CSS changes after an upgrade Advanced selectors or DOM structure changed. Move common branding to supported assets and tokens. Treat the stylesheet as customer-owned best-effort customization.