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
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.
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.
See the below article for details on how to run the end-to-end solution in a browser:
See the Curity OAuth for Web Home Page for all resources on this design pattern.
Please visit curity.io for more information about the Curity Identity Server.