Finsemble: Enabling Authentication

Enabling Authentication

By default, Finsemble applications do not require authentication (i.e. user sign-on), but hooks are available for developers to add an authentication component to match their specific application's needs. The Authentication Client API and underlying AuthenticationService allow developers to add a custom authentication component which forces end users to authenticate before proceeding.

Note: This API does not define a specific authentication protocol. It deals strictly with integration of Authentication into the UX.

Sample code for an authentication component is provided below.

Preview using built-in Sample Authentication

A sample authentication example is built into the Finsemble sample seed project. To enable this sample code in the gettingFinsemble (or your own project), set isAuthEnabled to true in configs/application/config.json. Once authentication is enabled, users will be prompted for a username and password when the application starts.

Note: With the Sample Authentication, users can enter any password since it isn't verified.

Note: Finsemble application data (e.g., workspace configuration), or any data saved with the Storage API, is keyed by username. Changing the username, even in the sample authentication, will affect the underlying storage. When authentication is disabled, the username defaults to "defaultUser".

Running Authentication From Your Own Project

To include and modify the authentication sample code in your own project (i.e. to make your own authentication component) follow these steps:

  1. If you don't already have a Finsemble project, create one on your local machine (see gettingFinsemble).
  2. From the sample repository, copy the authentication directory under src/components to your project's src/components directory. You will now have <your project path>/src/components/authentication/defaultAuthentication.html within your project.
  3. Customize this component by adding JavaScript code to interact with your authentication service.
  4. You'll now need to tell Finsemble to load this new component by adding it to your components.json file. The sample repository contains an example component entry. Open /configs/components.json and copy the complete "defaultAuthentication" property (a little over 30 lines) into your project's /configs/components.json file. Note: you can change the filename of your authentication component but the config property must be called "defaultAuthentication" for the authentication service to find it.
  5. In your project, edit <your project path>/node_fileserver/FinsembleConfigs.js. Enable authentication by adding the line Finsemble.enableAuthentication(true);.

Restart your Finsemble application. Your authentication component will now execute on startup.

Background: The Authentication Start-Up Sequence

When a Finsemble application with authentication enabled launches, the following authentication sequence occurs:

  1. The Authentication Service reads the "defaultAuthentication" property from the configs/components.json file to identify the authentication component.
  2. The Authentication Service spawns the authentication component and waits for a response.
  3. The spawned authentication component runs developer code to authentication the user. When complete, the developer invokes FSBL.Clients.AuthenticationClient.publishAuthorization(username, credentials) with the authenticated username and credentials. Credentials can be any object. The credentials will be available to Finsemble components that need access to it. Note, in cases where your authentication model requires handing control off to an authentication server (such as OAuth 2.0), then the "redirect page" from the authentication server should invoke publishAuthorization.
  4. Upon receiving the authentication response from the component (i.e. when publishAuthorization is invoked), the service publishes the authenticated username and credentials to all listeners on SubPub topic "Authorization" (see below).

Any Finsemble component or service can be an "authorization listener" to receive the authorization results by using the following SubPub subscription:

    RouterClient.subscribe("Authorization", function (err, response) {
        // do something with auth data contained in "response.data"
    } );

Note: Given credentials are available though SubPub subscription to any JavaScript with access to the application's Finsemble library, it is up to the authentication developer to decide if credentials should be encoded (or encrypted) to limit availability to a subset of components and/or services. If so, the credentials must be encoded outside the scope of Finsemble before publishing though publishAuthorization. Likewise, decoding steps would take place outside the scope of Finsemble by specific components after receiving the authorization notification.

More On the Sample Authentication-Component Code

Finally, let's outline what is in the sample code provided in defaultAuthentication.html. An inspection of the code shows it is only a sample implementation, but it does demonstrate a representative flow for authentication which can serve as a template for your implementation:

  1. HTML prompts for username and password

  2. The username and password are sent to an external server

  3. After a successful server response, publishAuthorization(username, credentials) is invoked to notify Finsemble of a successful authentication (i.e. the authentication service is notified, which publishes the authorization data to all interested listeners and continues with startup).

Finsemble itself is agnostic about which type of authentication a developer may choose to implement -- the only requirement is to pass back to Finsemble the results using publishAuthorization(). As mentioned before, if your authentication model requires handing control off to an external authentication server, then the "redirect page" you've specified to the external server must be the one to invoke publishAuthorization. It is also worth noting that Finsemble doesn't define what happens on authentication failure; it is up to the authentication component to determine how to handle failures (e.g. retry, terminate application, display error). Finsemble will simply not proceed with its startup sequence until a successful authentication.