OWASP Application Gateway

CI/CD

🏗️ OWASP Application Gateway is work-in-progress. No productive version has been released yet.

OWASP Application Gateway is an HTTP reverse proxy that sits between your web application and the client and handles Oauth2 login and session management. For you, as a developer, OWASP Application Gateway removes the hassle to implement complicated oauth2 logic in the backend and frontend so you can focus totally on your applications logic.

It is built on Spring Cloud Gateway Server MVC and runs on Apache Tomcat with Java 25 virtual threads: every request is handled on its own virtual thread, so there is no event loop and no thread pool to size. Note that WebSocket traffic is not proxied.

Table of Contents

• OWASP Application Gateway
  • Table of Contents
  • Design Principles
    • Secure by default
    • Stateless
    • Configuration based
  • Configuration File
  • How to run
    • Docker Release
    • Jar release
    • Compile it Yourself
  • Functionality
• Mascot

Design Principles

Secure by default

Implementing secure logins and session management became much more complicated within the last few years. OWASP Application Gateway aims to make this easier. Also, it implements many security hardening measures out of the box.

Stateless

Wherever possible, OWASP Application Gateway is stateless. All session information is stored within encrypted cookies on the clients. Stateless session management makes it a lot easier to deploy OWASP Application Gateway on multiple nodes.

Configuration based

OWASP Application Gateway's behavior is controlled with a central configuration file describing all routes and Oauth2 integrations. This makes it easier to review the configuration for security issues and to debug on different environments. The deployment and scaling are straightforward; configure the config file's file path, and that's all you need to do.

Configuration File

OWASP Application Gateway is fully configured with a simple and easy to understand configuration file. Details are documented in the GitHub doc.

hostUri: https://example.com

routes:
  httpbin:
    type: webapplication
    path: /**
    url: https://httpbin.org
    allowAnonymous: yes
  echo:
    type: webapplication
    path: /echo/**
    url: https://nellydemoapp.azurewebsites.net
    allowAnonymous: no

loginProviders:
  google:
    type: oidc
    with:
      authEndpoint: https://accounts.google.com/o/oauth2/auth
      tokenEndpoint: https://oauth2.googleapis.com/token
      clientId: 372143946338-48et57uhmcumku7am3ocvva0idc7u0td.apps.googleusercontent.com
      clientSecret: env:GOOGLE_CLIENT_SECRET
      scopes: [ "openid", "email" ]

  github:
    type: github
    with:
      authEndpoint: https://github.com/login/oauth/authorize
      tokenEndpoint: https://github.com/login/oauth/access_token
      clientId: 163ad3b08c3829216ba1
      clientSecret: env:GITHUB_CLIENT_SECRET
      scopes: [ "user", "email" ]

securityProfiles:
  webapplication:
    responseHeaders:
      Server: <<remove>>
      X-Powered-By: <<remove>>
      X-XSS-Protection: 1;mode=block;
      X-Frame-Options: SAMEORIGIN
      X-Content-Type-Options: nosniff
      Referrer-Policy: strict-origin-when-cross-origin
      Content-Security-Policy: base-uri 'self';object-src 'self'
      Permissions-Policy: geolocation=(),notifications=(),push=(),microphone=(),camera=(),speaker=(),vibrate=(),fullscreen=(),payment=(),usb=(),magnetometer=(),gyroscope=(),accelerometer=()
      Strict-Transport-Security: max-age=31536000; includeSubDomains


traceProfile:
  forwardIncomingTrace: true
  maxLengthIncomingTrace: 254
  acceptAdditionalTraceInfo: false
  maxLengthAdditionalTraceInfo: 254
  sendTraceResponse: true
  type: w3cTraceContext

How to run

You have three options on how to run OWASP Application Gateway:

• There is an official docker image that just works out of the box. You need to mount the config file via docker volumes.
• If you don't want to use docker, you can also download the released jar file. * Of course you can also build OWASP Application Gateway by yourself with Gradle. Note, that in all cases this starts the OAG with a self-signed certificate (This means you will get warnings in your browser when connecting.) It is recommended you change the certificate according to: Configure TLS.

Docker Release

You can find the Docker image at Docker Hub.

Download and Start:

# Download image of oag
docker pull owasp/application-gateway:main-SNAPSHOT

# Download sample config and adapt it to your needs
curl https://raw.githubusercontent.com/The-OAG-Development-Project/Application-Gateway/refs/heads/main/oag/sample-config.yaml >> oag-config.yaml
vim oag-config.yaml

# Start the container
docker run -e OAG_CONFIG_PATH=/app/oag-config.yaml -v ${PWD}/oag-config.yaml:/app/oag-config.yaml owasp/application-gateway:main-SNAPSHOT

Jar release

Point your browser to https://github.com/The-OAG-Development-Project/Application-Gateway/releases/latest Download the oag*.zip from the Assets section.

unzip oag*.zip
cd build/app
java -jar oag.jar

Compile it Yourself

The easiest way is to use Docker to build OWASP Application Gateway.

git clone https://github.com/The-OAG-Development-Project/Application-Gateway.git
cd Application-Gateway
docker build -t owasp/application-gateway:SNAPSHOT .
docker run -p 8080:8080 owasp/application-gateway:SNAPSHOT

If you don't want to use Docker you can build the jar by yourself with Gradle:

git clone https://github.com/The-OAG-Development-Project/Application-Gateway.git
cd Application-Gateway
cd oag
./gradlew assemble
java -jar build/libs/oag.jar

You may also use your IDE for building OAG. Please see Setup OAG for development for instructions using IntelliJ as an example.

Functionality

• TLS endpoint
• OpenID Connect Login with multiple providers
• Multiple Backend routes
• Authenticated routes
• Request Logging
• Add and remove response headers
• Secure, HTTP-only and same-site session cookies
• Forward id token to backend
• Upstream authentication with API key
• GitHub Login support
• Method whitelisting
• CSRF protection
• Rolling sessions
• W3C compliant request tracing

Ideas:

• Header whitelisting
• Report URI Endpoint
• Default configuration
• ...

Mascot