cagdasoezguer / oauth-agent-kotlin-spring

A Kotlin OAuth Agent, providing API driven OpenID Connect for SPAs

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

See the below article for details on how to run the end-to-end solution in a browser:

• SPA Code Example

Website Documentation

See the Curity OAuth for Web Home Page for all resources on this design pattern.

More Information

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