A Node.js OAuth Agent for SPAs

Overview

The OAuth Agent acts as a modern Back End for Front End (BFF) for Single Page Applications.
This implementation demonstrates the standard pattern for SPAs:

• Strongest browser security with only SameSite=strict cookies
• The OpenID Connect flow uses Authorization Code Flow (PKCE) and a client secret

Architecture

The following endpoints are implemented by the OAuth agent.
The SPA calls these endpoints via one liners, to perform its OAuth work:

Endpoint	Description
POST /oauth-agent/login/start	Start a login by providing the request URL to the SPA and setting temporary cookies
POST /oauth-agent/login/end	Complete a login and issuing secure cookies for the SPA containing encrypted tokens
GET /oauth-agent/userInfo	Return information from the User Info endpoint for the SPA to display
GET /oauth-agent/claims	Return ID token claims such as auth_time and acr
POST /oauth-agent/refresh	Refresh an access token and rewrite cookies
POST /oauth-agent/logout	Clear cookies and return an end session request URL

For further details see the Architecture article.

Deployment

Build the OAuth agent into a Docker image:

npm install
npm run build
docker build -t oauthagent:1.0.0 .

Then deploy the Docker image with environment variables similar to these:

oauth-agent:
  image: oauthagent:1.0.0
  hostname: oauthagent-host
  environment:
    PORT: 3001
    TRUSTED_WEB_ORIGIN: 'https://www.example.com'
    ISSUER: 'https://login.example.com/oauth/v2/oauth-anonymous'
    AUTHORIZE_ENDPOINT: 'https://login.example.com/oauth/v2/oauth-authorize'
    TOKEN_ENDPOINT: 'https://login-internal/oauth/v2/oauth-token'
    USERINFO_ENDPOINT: 'https://login-internal/oauth/v2/oauth-userinfo'
    LOGOUT_ENDPOINT: 'https://login.example.com/oauth/v2/oauth-session/logout'
    CLIENT_ID: 'spa-client'
    CLIENT_SECRET: 'Password1'
    REDIRECT_URI: 'https://www.example.com/'
    POST_LOGOUT_REDIRECT_URI: 'https:www.example.com/'
    SCOPE: 'openid profile'
    COOKIE_DOMAIN: 'api.example.com'
    COOKIE_NAME_PREFIX: 'example'
    COOKIE_ENCRYPTION_KEY: 'fda91643fce9af565bdc34cd965b48da75d1f5bd8846bf0910dd6d7b10f06dfe'
    CORS_ENABLED: 'true'
    SERVER_CERT_P12_PATH: '/certs/my.p12'
    SERVER_CERT_P12_PASSWORD: 'Password1'

If the OAuth Agent is deployed to the web domain, then set these properties:

COOKIE_DOMAIN: 'www.example.com'
CORS_ENABLED: 'false'

In development setups, HTTP URLs can be used and certificate values left blank.

OAuth Agent Development

See the Setup article for details on productive OAuth Agent development.
This enables a test driven approach to developing the OAuth Agent, without the need for a browser.

End-to-End SPA Flow

Run the below code example to use the OAuth Agent in an end-to-end SPA flow:

• SPA Code Example

Website Documentation

See the Curity Token Handler Design Overview for further token handler information.

More Information

Please visit curity.io for more information about the Curity Identity Server.