Financial.md

How to run the SPA with the Financial-grade OAuth Agent

Overview

The end-to-end solution provides the following behaviour:

• The OAuth Agent performs OAuth work for the SPA in an API driven manner
• Authorization Code Flow with PKCE is used, along with Mutual TLS client authentication
• PAR and JARM are also used, as state-of-the-art security features
• Only the strongest SameSite=strict cookies are used in the browser
• The code example uses HTTPS for all components

Configure Development Domains

Add these entries to your /etc/hosts file:

127.0.0.1 localhost www.example.com api.example.com login.example.com
:1        localhost

Install Prerequisites

Ensure that these tools are installed locally:

• Node.js 20 or later
• Java 17 or later
• Docker
• openssl
• jq
• envsubst

Contact Curity to get a trial license with access to financial grade features.
Then copy the license.json file to the folder where you have cloned this repository.

Also, ensure that your computer's Curity Docker image is up to date:

docker pull curity.azurecr.io/curity/idsvr

Build the Code

This will compile projects, build Docker images and generate development certificates if needed:

./build.sh 'FINANCIAL'

For further control you can override the script with options:

OAUTH_PROXY=''
./build.sh 'FINANCIAL' "$OAUTH_PROXY" 

OAUTH_PROXY supported values:

• KONG (default)
• NGINX
• OPENRESTY

Configure SSL Trust

Configure the browser to trust the root certificate authority at ./deployments/financial/certs/example.ca.pem.
For most browsers this can be done by importing it to the system trust store, eg Keychain Access / System / Certificates.

Deploy the System

Then run this script to spin up all components in a small Docker Compose network:

./deploy.sh 'FINANCIAL' 

If overriding default options, supply the same options to this script:

OAUTH_PROXY=''
./deploy.sh "FINANCIAL" "$OAUTH_PROXY" 

Use the System

Then browse to https://www.example.com and sign in with the following test user name and password:

• demouser / Password1

The SPA has an initial unauthenticated view to focus on triggering a login:

The authenticated view demonstrates multi-tab browsing, which works reliably in all browsers:

Deployed System

Once the system is deployed you can also browse to these URLs:

• Sign in to the Curity Admin UI with credentials admin / Password1
• Browse to the Identity Server Metadata Endpoint
• Browse to the SPA's OAuth Agent Base URL
• Browse to the Example API Base URL, which uses the OAuth proxy to forward JWTs to APIs

Deployment Details

To understand token handler deployment details you can study the build and deployment scripts.

Troubleshoot

If you need to troubleshoot, then access logs for the OAuth agent and OAuth proxy with these commands:

OAUTH_AGENT_CONTAINER_ID=$(docker container ls | grep oauth-agent | awk '{print $1}')
docker logs -f $OAUTH_AGENT_CONTAINER_ID

API_GATEWAY_CONTAINER_ID=$(docker container ls | grep api-gateway | awk '{print $1}')
docker logs -f $API_GATEWAY_CONTAINER_ID

Run UI Tests

If required, run the SPA's automated UI tests for login related operations:

cd spa
npm run uitests

Free Resources

When finished with your development session, run the following script to free resources:

./teardown.sh financial