Overview #

The login page is a fairly simple HTML document that uses CSS, images, and some JavaScript. The login page accepts a username and password as input, and submits that information to the server. The server attempts to authenticate users based on the credentials supplied, and then allows them to proceed or returns an error.

edgeCore includes a default system login page, shown below.

If the server is unable to authenticate a user based on Username or Password, it will return an error message which is displayed inline, as shown in the example below.

Customizing the Login Page #

The login page is one aspect of the product that gets customized frequently. It is often customized for branding reasons, but there are other checks (such as Terms of Use, for example) that are sometimes needed prior to logging into the application.

The default login page and resources can be used as a reference when creating a custom login page, but they should not be modified directly. Instead a custom location is provided which is part of the regular backup and restore process so that customizations will be preserved.

  1. Start by copying the system login page and resources into the custom login page location:
    1. from system location (including all sub-directories):
      [INSTALL_HOME]/tomcat/webapps/ROOT/WEB-INF/classes/static/login/
    2. to custom location:
      [INSTALL_HOME]/static-web/login/
  2. The HTML page must be [INSTALL_HOME]/static-web/login/login.tpl.html (unless the Custom Login Page location is changed – see below), but this will be the case if copying the default system files.
  3. Modify the HTML, CSS, and image resources as required. Note that these resources may be cached by your browser so be sure to clear the browser cache after modifications, or disable the cache while working.
  4. Changes are immediate. edgeCore will serve the custom login page rather than the system login page. In order to revert to the system login page, move the files from the custom location.
  5. It is recommended that the basic structure of the HTML form be preserved (input fields, ids, names, etc) so that the default Javascript continues to work.  Otherwise changes to the js/edgeLogin.js file will be required and that is beyond the scope of this document.

Changing the Custom Login Page Location #

By default, the custom location is configured as mentioned above. However, this can be modified to point to a different directory under [INSTALL_HOME]/static-web/ if desired. For example if multiple custom login pages need to be maintained and you need to switch between them. This can be done via the Provisioning Defaults administration page. Note that changing the login page location will require a system restart.

Customizing the Login Page JSP #

This allows for some additional modifications when the steps above are not sufficient.  In this step the backing JSP used by the Login Controller will be modified to enrich the login experience.  JSP’s are mapped uniquely by edgeCore’s registered controllers.

The default login.edgejsp is used as a reference when creating a custom login flow; but they should not be modified directly.  Instead make a copy in [INSTALL_HOME]/jsp/login.edgejsp and modify that file instead; as any changes made directly in /WEB-INF/jsp are lost on server restart and/or re-initialization.

  1. Start by copying the system login.edgejsp
    1. from system location (including all sub-directories):
      [INSTALL_HOME]/tomcat/webapps/ROOT/WEB-INF/jsp/login.edgejsp
    2. to custom location:
      [INSTALL_HOME]/jsp/login.edgejsp

Changing the Error Messages #

edgeCore will present error messages to users in certain situations related to login. The administrator can configure these error messages, if desired, by modifying the following file:

[Install_Home]/tomcat/webapps/ROOT/WEB-INF/classes/static/login/html/login.tpl.html

The edgeSuite server will log the reason for a failed login. However, for the client (user) to see the appropriate ‘status’, the administrator would need to make sure the relevant block exists. Administrators are free to change the messages by editing the login template file. Care should be taken to ensure that some message is provided so it is clear that the login was submitted and a failure occurred.

The following settings are available in all versions of edgeCore:

                                   <div ng-if=”ctrlr.loginState.status ===’badAuth'” class=”alert alert-danger”>

                                        Could not authenticate user: {{ctrlr.loginState.username}}

                                    </div>

                                    <div ng-if=”ctrlr.loginState.status ===’locked'” class=”alert alert-danger”>

                                        Account is locked. Please contact your system administrator.

                                    </div>

                                     <div ng-if=”ctrlr.loginState.status ===’lostSession'” class=”alert alert-danger”>

                                        Your session may have timed out, or communication with the server has been lost.

                                    </div>

                                    <div ng-if=”ctrlr.loginState.status ===’unreachable'” class=”alert alert-danger”>

                                        The server cannot be reached.  Please contact your system administrator.

                                    </div>

                                    <div ng-if=”ctrlr.loginState.status ===’loggedOut'” class=”alert alert-success”>

                                        You have been successfully logged out.

                                    </div>

The following additional settings are available in edgeCore v3.7 or higher:

                                     <div ng-if=”ctrlr.loginState.status ===’sessionLimit'” class=”alert alert-danger”>

                                        Number of active sessions exceeds license. Please contact your system administrator.

                                    </div>

                                    <div ng-if=”ctrlr.loginState.status ===’userLimit'” class=”alert alert-danger”>

                                        Number of users exceeds license. Please contact your system administrator.

                                    </div>

                                    <div ng-if=”ctrlr.loginState.status ===’domainLimit'” class=”alert alert-danger”>

                                        Number of domains exceeds license. Please contact your system administrator.

                                    </div>