Skip to content

Latest commit

 

History

History
107 lines (75 loc) · 3.37 KB

Development.md

File metadata and controls

107 lines (75 loc) · 3.37 KB
Raw

Development

This document is intended for developers who are interested in learning how to modify and test the Helix Authentication Service.

Setup

Prerequisites

To fetch and build the application dependencies and run tests, you will need Node.js LTS or higher.

Build and Start

Configure the authentication service as described in the documentation, then build and start the authentication service:

$ npm install
$ npm start

Docker

Refer to the README.md file in the containers directory for instructions.

Authentication Extension

The containers for the extension for integrating the authentication service with Helix Core are in a separate repository and can be installed using docker compose as described in the documentation for that project.

Automated Testing

Some automated tests are provided for ensuring basic operational soundness (e.g. user can authenticate via IdP, application can retrieve user profile data). The login tests utilize the Selenium webdriver to start Firefox in headless mode. As such, a recent release of Firefox must be installed on the test system. Additionally, the Docker containers defined in docker-compose.yml must be built and running.

$ docker compose build auth-svc1.doc
$ docker compose up --build -d
$ npm test

Testing without Docker

Many of the unit tests do not use the .doc Docker containers and thus most of the test suite can be run using this command:

$ npm unit

Running individual tests

To run a single test, use npx mocha as shown in the example below:

$ npx mocha --exit test/features/login/domain/usecases/GetSamlAuthnContext.test.js

If the test makes use of setTimeout() then add the --delay flag:

$ npx mocha --exit --delay test/features/login/presentation/routes/requests.test.js

Running the Service on HTTP

If for some reason you do not want the auth service to be using HTTPS and its default self-signed certificate, you can use HTTP instead. This is particularly relevant when developing with a browser that refuses to open insecure web sites, such as the SAML Desktop Agent with its embedded Chromium browser.

To switch from http: to https: you will need to change at least three settings:

  1. Set SVC_BASE_URI appropriately in the auth service configuration.
  2. Set service URL in the client system (e.g. Perforce server).
  3. Set the callback URL in the identity provider.

Coding Conventions

With respect to the JavaScript code, the formatting follows StandardJS. The linter available in Atom is very good, and catches many common coding mistakes. Likewise with Visual Studio Code and the StandardJS extension.

Design: Sequence Diagram

The sequence_diagram.mmd uses mermaid syntax, which the mermaid.cli tool reads to produce the diagram of the authentication workflow.

To generate the diagram, invoke mmdc like so:

$ npm install -g mermaid.cli
$ mmdc -i docs/sequence_diagram.mmd -t neutral -o flow.png