Note: This repository is templated as part of di-ipv-cri-templates, and any substantial changes that can be shared should be included back into that repository for re-use elsewhere
KBV HMRC Credential Issuer Frontend is a Credential Issuer as part of the GOV.UK One Login programme.
There are two main repositories that comprise this credential issuer:
- This is the website used for displaying the Kbv Hmrc Credential Issuer.
- There is a related api repository that contains the backend API that provides all the data interaction consumed
For frontend specific work there are the following repositories:
- There is a shared library repository
- This contains Express middleware, shared JavaScript and Sass files, and shared templates
The following quickstart process details how to install and run the CRI frontend webserver with API mocks.
- Node.js (>= 20.11.1)
- NPM (>= 9.6.0)
- pre-commit (>= 2.17.0)
- Clone repository and change directory:
git clone https://github.com/govuk-one-login/ipv-cri-kbv-hmrc-front && cd ipv-cri-kbv-hmrc-front
- Install node dependencies:
npm install
- Build the assets
npm run build
Create a copy of the example environment variable file and add values for the keys:
cp .env.example .env
Set the environment variables accordingly.
In order to successfully run the application, the following things are required:
- frontend application started and configured to point at an API
- deployed API or mock API needs to be made available and configured
- a correctly formed entry point url using
client_idandrequestOAuth parameters
The app will run on port 5000 by default and be available at http://localhost:5000.
To run the server with continuous build mode:
npm run dev
Note: By default, the server runs with an in-memory Redis instance, so restarting the server will clear the session.
By default, the application will be running at http://localhost:5000.
To run the server with debug logs and attach a debugger (will not rebuild on changes):
npm run debug
Note: You'll need to create a debug "attach" configuration in your IDE in order to attach the debugger and set breakpoints. In VSCode create a
.vscode/launch.jsonfile with a Node.jsattachconfiguration.
NODE_ENV=production npm start
An API is required for all oauth requests and all other backend interactions.
This is configured in the frontend application using the API_BASE_URL environment variable, as described in environment variables.
A standalone mock of the api is provided using a combination of the API's OpenAPI config and hand-crafted Imposter scenarios.
More details on how to run this are in the Imposter folder.
When connecting to a mock API both the client_id and request parameters are determined by the data in the Imposter configuration files. The client_id determines the session_id which is then used for determining what data to return to the frontend, and the request parameter is ignored.
This can also be connected to a deployed API behind an API Gateway, using the same API_BASE_URL variable.
When connecting to a deployed API both the client_id and request parameters are supplied by an upstream service acting as this system's Relying Party. The client_id is configured for use with API and the request payload is signed and encrypted with keys known to the API.
Using the appropriate client_id and request parameters, the website can be accessed using a URL similar to:
http://localhost:5000/oauth2/authorize?request=ignored&client_id=success
Unit tests can be run from the root of the project using:
npm run dev
They use Jest as the test runner, which is configured using jest.config.js
Browser tests are run from the tests/browser folder, with appropriate quick start documentation located there.
The codebase is released under the MIT License.