Jump to content
We've recently updated our Privacy Statement, available here. ×

  • Create a Custom Login Page in Spotfire®

     Share

    Introduction

    The purpose of this page is to describe how you can create a custom login page for username/password authentication. These instructions represent the way to create custom login pages for Spotfire versions before Spotfire® 11.4 LTS.

    Deprecating the AngularJS Custom Login Page API

    However, the AngularJS-based API for creating a Custom Login Page for Spotfire is deprecated, starting with Spotfire Server 11.4.0 LTS. It will be completely removed in a later version of the Spotfire® Server. AngularJS has set an end-of-life date for its LTS on December 31st, 2021.

    Instead, the new Custom Login Page API, for 11.4.0 LTS and forward, does not rely on a framework, and it is written in vanilla JavaScript, so that you are not required to learn a framework or depend on framework-breaking changes in the future.

    Use Cobranding for customizing Spotfire products

    The standard way to customize products related to Spotfire (including the Spotfire Server web interface, or TSS Web UI) is to use Spotfire Cobranding.

    Use the Package Builder tool to create a package, and then upload that package using the TSS Web UI Deployments & Packages page.

    From TSS 11.4.0 LTS, the Custom Login Page feature should be used with the cobranding system.

    Read more about cobranding in the Spotfire® Cobranding guide.

    Migrating from the AngularJS to the Cobranding Custom Login Page

    If you already have a custom login page that relies on the AngularJS implementation, see Migrate an Existing Custom Login Page in Spotfire® for instructions on how to migrate it to the Cobranding custom login page.

    Instructions for custom login using AngularJS (Spotfire 11.3 and earlier)

    A custom login page for username/password authentication can be created using the following steps. It may be combined with a custom PostAuthenticationFilter for additional verification or other advanced scenarios. The example also shows an example for when the server is configured with web authentication providers.

    See examples in the attached file.

    See also:

    Requirements

    • The implementation must be based on AngularJS. Example: 
      angular.module("tssCustomLoginAppController",
[
    "app.api"
])
.controller("tssCustomLoginAppController", function ($scope, apiService, apiHttp) {
    ...
});
       

    • Anything that could clash with the TSS codebase needs to be prefixed: 

       tssCustomLogin.
       

    Configuration

    A custom login page can be configured through the security.basic.login-page configuration property:

    The value should be a URL, relative to the /spotfire web application. It must reside under /resources/custom-login/ and end with .html.

    Configuration example (using the command line). For instructions on using the Spotfire command line, see the help topic Executing commands on the command line. 

     config set-config-prop -n "security.basic.login-page" -v "/resources/custom-login/custom-login-app-example.html"
     

    To see the web authentication provider example, this option must be enabled and at least one provider must be added.

    JavaScript Libraries included

    Library Alias Version
    jQuery $ 2.1
    lodash _ 3.10
    AngularJS angular 1.3

    Files

    The new files along with the HTML page should be added to <tss-install-dir>/tomcat/webapps/spotfire/resources/custom-login/. Create the folder if it does not exist.

    Build id

    The <build-id> can be found in the <tss-install-dir>/tomcat/webapps/spotfire/login.html file, on the existing includes. This will change for every new version of the Spotfire Server.

    HTML File

    • <head>-tag must contain the attribute angular-app where the value is the name of the AngularJS application.

       

       

    • <head>-block must contain JavaScript and CSS includes where <build-id> is the version of the files: 
      <link rel="stylesheet" type="text/css" href="/spotfire/resources/min/app.css?<build-id>">
<script type="text/javascript" src="/spotfire/resources/min/third-party.js?<build-id>"></script>
<script type="text/javascript" src="/spotfire/resources/min/app.js?<build-id>"></script>
<script type="text/javascript" src="/spotfire/resources/min/customization.js?<build-id>"></script>
       

    • Any new JavaScript and/or CSS files are included by adding additional includes: 

       <script type="text/javascript" src="/spotfire/resources/custom-login/custom-login-app-example.js"></script>
       

    API

    The API constitues of an AngularJS module names app.api

    It contains two AngularJS components named apiService and apiHttp.

    apiService.redirectToTargetUrl 

    /**
 * Decodes the targetUrl query parameter and redirect the user to that URL.
 * If no URL is present or URL is invalid, the user will be directed to a
 * default URL.
 *
 * URL must be relative and start with /spotfire/
 *
 * @since 7.6
 */
     

    apiService.login 

    /**
 * Encodes the username, password and any optional parameters supplied
 * and posts them to the Spotfire Server along with remember me value if that
 * setting is enabled.
 *
 * @param  {string} username the username
 * @param  {string} password the password
 * @param  {boolean} allowSaveInformation if the remember me
 * functionality is enabled
 * @param  {boolean} saveLoginInformation the actual value of
 * remember me
 * @param  {function} [errorCallback] callback executed if
 * login attempt result in an HTTP status code greater than or equal to 400
 * @param  {function} [successCallback] callback executed when
 * the login attempt is successful
 * @param  {object} [optionalPayload] optional payload that is encoded and passed
 * along in the request body. All keys must be prefixed with sf_custom_login_.
 * These parameters will be available to PostAuthenticationFilter
 * implementations as a map attribute through the AuthenticationContext
 * (details can be found in the Javadoc for AuthenticationContext).
 *
 * @since 7.6
 */
     

    apiService.retryCsrf 

    /**
 * Retries the HTTP request with an updated CSRF token if the request and cookie value differs.
 *
 * @param  {object} rejection the Angular rejection object.
 * @param  {function} errorCallback the callback executed in case of HTTP request error.
 * @param  {function} successCallback the callback executed in case of HTTP success.
 *
 * @since 7.6
 */
     

    apiService.redirectToWebAuthProvider 

    /**
 * Redirects to the web authentication (e.g. OpenID Connect) provider. Will check targetUrl
 * query parameter and pass that along to the web auth provider.
 *
 * @param  {string} providerName the name of the provider.
 * @param {function} [errorCallback] optional - error callback that executes if the call to
 * getting the authenticaion endpoint would fail.
 *
 * @since 7.7
 */
     

    apiHttp.manifest 

    /**
 * Makes a web service call that retreives information:
 *
 * @param {function} successCallback the callback called when request is resolved successfully.
 * * @param {function} errorCallback the callback called when request failed.
 * @returns {Object}:
 * {
 *   allowSaveInformation: boolean // True if the server has remember me functionality enabled
 *   loginPageUrl: "/spotfire/resources/custom-login/custom-login-app-example.html" // The path to the currently configured login page.
 *   showLoginPage: boolean // False if the server thinks the user is already logged in.
 * }
 *
 * @since 7.6
 *
 **************************
 * Makes a web service call that retreives information:
 *
 * @param {function} successCallback the callback called when request is resolved successfully.
 * * @param {function} errorCallback the callback called when request failed.
 * @returns {Object}:
 * {
 *   allowSaveInformation: boolean // True if the server has remember me functionality enabled
 *   showLoginPage: boolean // False if the server thinks the user is already logged in.
 *   formsDisabled: boolean, // True if form based login is disabled.
 *   webAuthProviders: // List of web auth providers
 *   [
 *     {
 *       color:null, // Color of button
 *       imageUrl:null, // Image URL to an icon for the button
 *       label:"Google", // The text displayed on button.
 *       providerName:"https://accounts.google.com" // The provider name
 *     }
 *     ...
 *   ]
 * }
 *
 * @since 7.7
 */
     

    Attachments

    Download From Resources

    tib_sfire_server_custom_login_page_api_example.zip

     Share
    Go to articles

    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...