A Kotlin 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 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:

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'
    USE_SSL: '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 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:

• 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.