Modules: Custom Login Page

2024-03-29

This topic describes how to create and deploy a custom login page on LabKey Server. A custom login page can incorporate custom text or images, enhancing the branding of your server or providing site-specific guidance to your users.

Module Structure for Login Page

A custom login page is defined as a view in the module of your choice. Learn more about module structures here: Map of Module Files. Note that there will be other files and folders in the module that are not shown in this illustration.

MODULE_NAME  └──resources       └──views            LOGIN_PAGE_NAME.html

For example, if you were using a module named "myModule" and your page was named "myLoginPage.html" the relative path would be:

/myModule/resources/views/myLoginPage.html

Create Custom Login Page

By default, LabKey Server uses the login page found in the server source at /server/modules/core/resources/views/login.html.

Use the standard login page as a template for your custom page.

  • Copy the template HTML file into your module (at MODULE_NAME/resources/views/LOGIN_PAGE_NAME.html)
  • Modify it according to your requirements.

Note that the standard login page works in conjunction with:

The login.js file provides access to the Java actions that handle user authentication, such as loginApi.api and acceptTermsOfUseApi.api. Your login page should retain the use of these actions.

Example: Redirect Users After Login

When users log in, the default landing page is "/Home/project-begin.view?". If you wanted to redirect users to a different location every time, such as "/OtherProject/Example/project-begin.view?" you could edit the default login.js file to replace this portion of the success callback, specifying a new path for window.location:

if (response && response.returnUrl) {
window.location = response.returnUrl;
}
...with this explicit setting of the new window.location (regardless of any returnURL that might have been passed):
if (response && response.returnUrl) {
window.location = "/OtherProject/Example/project-begin.view?";
}

If you want to retain any passed returnURL parameter, but redirect the logged in user to your new location if none is passed, use this version:

if (response && response.returnUrl) {
if (response.returnUrl === "/labkey/home/project-begin.view?") {
window.location = "/OtherProject/Example/project-begin.view?";
} else {
window.location = response.returnUrl;
}
}

Note that the window.location path can be a full URL with the server specified, or as show above a path on the local server (making it easier to move between staging and production environments. A relative URL must always include the leading slash, and the context path, if present. For example, on a localhost development machine, you might need to use "/labkey/OtherProject/Example/project-begin.view?".

Enable Custom Login Page

Build and deploy your module and restart your server so that it will recognize the new page resource. Once you have deployed your custom login page, you will need to tell the server to use it instead of the standard login page. Note that you must have "AdminOperationsPermission" to update this setting.

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Look and Feel Settings.
  • Enter the Alternative login page using the format "MODULE_NAME-LOGIN_PAGE_NAME". You do not include the full path or file extension. In our example, this would be:
    myModule-myLoginPage
  • Click Save.

For details see Look and Feel Settings.

Related Topics