Preparation

• Install Java 25 or higher
• Install Gradle
• Install Git
• Install IntelliJ (Community Version is fine)
• git clone the OAG repository:
  • create a new folder for OAG:

  mkdir oag

  • jump into the folder:

  cd oag

  • clone the repository:

  git clone https://github.com/The-OAG-Development-Project/Application-Gateway.git

Import project

• Start IntelliJ.
• Open project: ../oag/Application-Gateway/oag
  • This should trigger Gradle and download dependencies

Build project

Using IntelliJ

• In IntelliJ Build of the whole project (select Build -> Build Project in the menu).
  • You will have to select a project JDK (IntelliJ prompts for this in the upper right corner.). OAG requires a SDK/JDK >= 25 and runs on Java 25 or higher.

Using Gradle

• In the command line change to ../oag/Application-Gateway/oag

  ./gradlew build

Package cycles

PackageCycleTest (ArchUnit, oag/src/test/java/org/owasp/oag/architecture) fails the build when the production code contains a package cycle. Every package below org.owasp.oag is its own slice. The root package org.owasp.oag holds only the application entry points, so no other package may depend on it.

LayeringTest (same package) guards the layering: no class outside org.owasp.oag.filters.servlet depends on the servlet filters. They are wired by component scan; shared helpers such as cookies.CookieReader live outside them.

Run project

Using IntelliJ

• Verify tests are green: Right click on the top level of the project ("oag" in the Project window) and select "Run All Tests"
• Run the gateway:
  • Open class OWASPApplicationGatewayApplication
  • Click the green triangle (Line 7) to run OWASPApplicationGatewayApplication.main().

Using Gradle

• In the command line enter:

  ./gradlew bootRun

• This starts the gateway on Tomcat with Java 25 virtual threads; every request is handled on its own virtual thread, so debugging a request means following one plain sequential stack trace.

Notes on client secrets / prerequisites

• You need 3 client secrets (i.e. registered OAG as an application in Google, GitHub and oAuth0) to be fully functional with the default sample configuration.
• For GitHub, this means you will have to register an oAuth App in GitHub. Not that the app needs to reflect your local OAG that runs in IntelliJ.
• If you do not have these 3 client secrets you will see the following in the logs:

WARN  - Environment variable 'GOOGLE_CLIENT_SECRET' does not exist
WARN  - Environment variable 'GITHUB_CLIENT_SECRET' does not exist
WARN  - Environment variable 'AUTH0_CLIENT_SECRET' does not exist

• these 3 clientID's can be set as environment variables in the operating system or directly in IntelliJ as follows:
  • Menu: Run -> Edit Configuration
  • "+" (Add new Configuration) -> Application (or edit the existing entry)
  • select "org.owasp.oag.OWASPApplicationGatewayApplication" as Main Class
  • in the text field for "environment variables:" add the 3 Secrets: " GOOGLE_CLIENT_SECRET=xxxxx;GITHUB_CLIENT_SECRET=xxxxxx;AUTH0_CLIENT_SECRET=xxxxxx"

Verify the gateway is running

• Point your browser to: https://localhost:8080/echo/ -> Note "X-Oag-Status: anonymous" in the returned page
  • Click on "Login with Github"
  • Enter your GitHub credentials
  • If all works fine you will end up on localhost:8080 which displays "httpbin.org"
• Point your browser again to: https://localhost:8080/echo/ -> Note "X-Oag-Status: authenticated" in the returned page

Now you are ready to develop new features in OAG. With this you are ready to develop.

Documentation vitepress

Install node.js: https://nodejs.org/en/download

Install vitepress (Folder ApplicationGateway/www):

cd www
npm add -D vitepress@next

Build the documentation:

cd www
npm install
npm run docs:build

(see package.json for more commands)

When using AI / Claude Code

Start claude in root folder Application-Gateway. Use Plugin superpowers.