Customizing the login page

This example demonstrates how to customize authentication if you need to create a custom login page for MicroStrategy Library. The customization in this example requires only two custom files—a JSP file for the custom login page and an XML configuration file that Spring Security uses during authentication. However, depending on the requirements for your customization, you may need to add additional custom resources such as CSS files, JavaScript files, and so on.

To help you get started, we have provided the following sample files:

Use the code in these files as a basis for your customization. The only difference in the 2021 Update 1 or newer file is that the customUnprotectedResources ID has been replaced with customResources in the StdConfig.xml file. This customization can be used with either standard or LDAP authentication.

Prerequisites

MicroStrategy Library is deployed
MicroStrategy Intelligence Server is running

JSP and XML files used in the customization

LoginPage.jsp
StdConfig.xml

To try out the customization in MicroStrategy Library, follow the instructions below.

Download the sample files and extract the contents.
Deploy your MicroStrategy Library application.

Create a JSP file that defines your custom login page and deploy it in Library.

Using a text editor, either open the LoginPage.jsp file that you downloaded or create a JSP file that defines your custom login page. Sample code for a simple login page using LoginPage.jsp is shown below:

Copy

<%@ page language="Java" import="java.util.*" %>
<%
String contextPath = request.getContextPath();
%>
<!DOCTYPE html>
<HTML>
  <head>
    <title>Custom Login Form</title>
  </head>
<BODY>
  <h1>Custom Login</h1><p>
  <form action="<%= contextPath %>/custom/auth/login" method="post">
    <div>
      <label for="name">Name:</label>
      <input type="text" id="login_name" name="login_name">
    </div>
    <div>
      <label for="mail">Password:</label>
      <input type="text" id="pswrd" name="pswrd">
    </div>
    <div class="button">
      <button type="submit">Login</button>
    </div>
  </form>
</BODY>
</HTML>

In the root folder of your deployed MicroStrategy Library application, create a folder named custom, and then create a folder named ui under custom.
Save your custom JSP login page under custom/ui as LoginPage.jsp.

If you are adding additional custom resources such as CSS files, JavaScript files, and so on, you should save them in the same location.

Create a custom XML configuration file that allows your custom login page to be used during authentication and deploy it in Library.

In the root folder of your deployed MicroStrategy Library application, navigate to WEB-INF\classes\auth\ and create a new folder called custom.
In the same root folder, navigate to WEB-INF\lib\ and use 7-Zip to open restful-api-1.0-SNAPSHOT-jar-with-dependencies.jar.
In the opened JAR file, navigate to auth\custom\ and copy StdConfig.xml to the custom folder you just created.

Open StdConfig.xml in a text editor and add a custom bean definition and a custom list of unprotected resources, as described below.

When you open WEB-INF\classes\auth\custom\StdConfig.xml , it should look like the code sample below.

Copy

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
              http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
              http://www.springframework.org/schema/context
              http://www.springframework.org/schema/context/spring-context-4.1.xsd
              http://www.springframework.org/schema/util
              http://www.springframework.org/schema/util/spring-util-4.1.xsd">
til-4.1.xsd">
</beans>

Before the closing </beans> tag, add the code for the bean definition and list of unprotected resources you need to override.
- loginPageUrl
  
  This code overrides the bean definition for the login page so that it points to the JSP file you created for the custom login page.
  Copy
```

    <bean id="loginPageUrl" class="java.lang.String">
        <constructor-arg value="/custom/ui/LoginPage.jsp"/>
    </bean>
```
- customResources (2021 Update 1 and newer)
  or
  customUnprotectedResources (2021 Platform Release or older)
  
  This code adds the contents of the custom/ui folder to the list of unprotected resources. This information is used by Spring Security to allow your custom login page to be used for authentication.
  Copy
```
  
    <util:list id="customResources">
        <value>/custom/ui/**</value>
    </util:list>
```

Save StdConfig.xml. Your file should look like the one shown below.

Copy

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.1.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-4.1.xsd">

    <!-- Override bean defining login page URL -->
    <bean id="loginPageUrl" class="java.lang.String">
        <constructor-arg value="/custom/ui/LoginPage.jsp"/>
    </bean>
    <!-- Add list of unprotected resource.
         (The main list of unprotected resources is defined in MainConfig.xml)
     -->
    <util:list id="customResources">
        <value>/custom/ui/**</value>
    </util:list>

</beans>

Use the customization in MicroStrategy Library.

To deploy your customization, restart your web server. When you open MicroStrategy Library, your custom login page appears.