Replacing the default Login page in the Spotfire Server web UI

You can create a custom login page using the cobranding functionality. This topic describes how to create a custom login for username/password authentication, or using third-party web authentication providers.

About this task

Note: A custom login page cannot contain inline styles or scripts (such constructs will be blocked by the Content Security Policy).

Before you begin

You have a cobranding.config file to work with. If you need one, see Creating a cobranding.config file.
In addition to the configuration file, you need the following files (links to templates and instructions are provided in the steps below):
- An HTML file for the login page. The contents of this file are injected into the Spotfire Server web interface (for example, custom-login-app-example.html).
- A JavaScript glue module. This file is the link between your HTML file and the Custom Login Page API (for example, custom-login-app-example.js).
- A CSS file (Optional. For example, custom-login-app-example.css).

Procedure

Open the cobranding.config file in an XML editor or text editor.
Locate the section <web>...</web> and add the row <customLoginPage>custom-login-app-example.html</customLoginPage>, pointing to your custom html page.
Example:
```
<cobranding>
  .....
  <web>
	    <customLoginPage>custom-login-app-example.html</customLoginPage>
  </web>
  .....
</cobranding>
```
Write or update your custom login HTML page. See The custom-login-app-example.html template for an example to begin with.
Important: The HTML file must not contain the <html>, <head> or <body> tags. The contents of this file are injected into the Spotfire Server web interface, which is an HTML file that contains these elements.
In the HTML file, make sure you import the following external files:
- The JavaScript module glue script.
- Optionally, the external CSS file.
Note: Because you upload these files using the cobranding mechanism, the path of these files is dynamic. To reference them correctly in your HTML, prefix them with /[%AppPath%]/ .

Example:
```
<script type="module" src="/[%AppPath%]/custom-login-app-example.js"></script>
<link rel="stylesheet" href="/[%AppPath%]/custom-login-app-example.css" />
```
Continue by adding the HTML elements needed on your custom login page.
For handling the interaction between your custom login page and the Custom Login Page API, write a glue JavaScript module. See The custom-login-app-example.js template. In this file, you can listen to events in your login page, change the DOM, and call the API as needed.
Important: The implementation must be based on JavaScript. Import the Custom Login Page API JavaScript module in your JavaScript glue module and instantiate it.
Example:
```
import TSSCustomLoginApi from "/spotfire/js-api/custom-login-api.js";
const customLoginApi = new TSSCustomLoginApi();
```
Optionally, create or update the external CSS file. See The custom-login-app-example.css template.
Place your files (the configuration file, the HTML page, the glue script, and, optionally, the CSS file) together in a directory on your computer, and then follow the instructions in Creating and deploying a cobranding package.

Results

When the cobranding package has been deployed, end users who try to login will see the custom login page instead of the default login page.

Note: If both a custom header and a custom login page are part of the cobranding package, then the custom header will not be shown on the custom login page. This limitation happens because all styles are stripped from a custom login page and then re-inserted, to make them CSP-compliant, and that can result in the styling not being applied correctly on the custom login page. However, the custom header will be available on any other page in the web interfaces of Spotfire, even if it is missing on the login page.