Create a Custom Login Page in TIBCO Spotfire®
Last updated:
11:33am Jun 08, 2017

Introduction

This page describes how to create a custom login page for username/password authentication. 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

CSS Libraries Included

Library Alias Version
Bootstrap .twbs 3.0

Files

The new files along with the HTML page should be added to <tss-install-dir>/tomcat/webapps/spotfire/resources/custom-login/. Create 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-lib.css?<build-id>">
    <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:

    <link rel="stylesheet" type="text/css" href="/spotfire/resources/custom-login/custom-login-app-example.css">
    <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

Feedback (2)

Thank you pmaske.  I've added a link to the help topic that explains how to use the command line.

dbendel 11:39am Jun. 08, 2017

I followed the above instructions, however the new login page was not coming into effect. I noticed that although we are setting the property for the security.basic.login-page, we are not importing the configuration into the database. I had to run the following additional command to get it working.

After running the command

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

Please also run

   config import-config --comment="CustomLoginConfig" configuration.xml

Please restart the Spotfire Server to pick up the new configuration.

pmaske 12:08am May. 29, 2017