Skip to content


Repository files navigation

A Java based OAuth Agent for Financial Grade SPAs

Quality Availability


The OAuth Agent provides a modern API driven Back End for Front End (BFF) for Single Page Applications.
This implementation provides state-of-the-art security suitable for financial-grade:

  • Strongest browser security with only SameSite=strict cookies
  • Financial-grade OpenID Connect flow using PAR, JARM and a Mutual TLS secret

Logical Components


The following endpoints are used so that the SPA uses simple one liners to perform its OAuth work:

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

For further details see the Architecture article.


Build the OAuth agent into a Docker image:

./gradlew bootJar
docker build -t oauthagent:1.0.0 .

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

  image: oauthagent:1.0.0
  hostname: oauthagent-host
    PORT: 3001
    AUTHORIZE_ENDPOINT: 'https://login-internal/oauth/v2/oauth-authorize'
    TOKEN_ENDPOINT: 'https://login-internal/oauth/v2/oauth-token'
    JWKS_URI: 'https://login-internal/oauth/v2/oauth-anonymous/jwks'
    USERINFO_ENDPOINT: 'https://login-internal/oauth/v2/oauth-userinfo'
    CLIENT_ID: 'spa-client'
    CLIENT_SECRET: 'Password1'
    SCOPE: 'openid profile'
    COOKIE_NAME_PREFIX: 'example'
    COOKIE_ENCRYPTION_KEY: 'fda91643fce9af565bdc34cd965b48da75d1f5bd8846bf0910dd6d7b10f06dfe'
    CORS_ENABLED: 'true'
    SERVER_CERT_P12_PATH: '/certs/myserver.p12'
    SERVER_CERT_P12_PASSWORD: 'Password1'
    CLIENT_CERT_P12_PATH: './certs/myclient.p12'
    CLIENT_CERT_P12_PASSWORD: 'Password1'
    CA_CERT_PEM_PATH: './certs/myrootca.pem'

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


OAuth Agent Development

See the Setup article for details on setting up an OAuth Agent development environment with an
instance of the Curity Identity Server. 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:

Website Documentation

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

More Information

Please visit for more information about the Curity Identity Server.