We track bugs and issues using Github.

If you find a bug, please open an Issue. When opening an Issue or Pull Request please follow the preconfigured template and take special note of the checkboxes.

If you want to fix a bug, add a new feature or extend existing functionality, please create a fork, create a feature branch and open a PR back to this repo. Please mention open bug issue number(s) within your PR if applicable.

We suggest using Visual Studio Code with the official Go for Visual Studio Code extension.

Go version

This project is currently still using go 1.22. You can follow the installation guide for go here. And you can find go version 1.22 in the archived section here.

Preparing your fork

Clone your fork, create a feature branch and update the depedencies to get started.

git clone [email protected]:<YOUR_FORK>/oauth2-proxy
cd oauth2-proxy
git branch feature/<BRANCH_NAME>
git push --set-upstream origin feature/<BRANCH_NAME>
go mod download

Testing / Debugging

For starting oauth2-proxy locally open the debugging tab and create the launch.json and select Go: Launch Package.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch OAuth2-Proxy with Dex",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}",
            "args": [
                "--config",
                // The following configuration contains settings for a locally deployed
                // upstream and dex as an idetity provider
                "contrib/local-environment/oauth2-proxy.cfg"
            ]
        },
        {
            "name": "Launch OAuth2-Proxy with Keycloak",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}",
            "args": [
                "--config",
                // The following configuration contains settings for a locally deployed
                // upstream and keycloak as an idetity provider
                "contrib/local-environment/oauth2-proxy-keycloak.cfg"
            ]
        }
    ]
}

Before you can start your local version of oauth2-proxy, you will have to use the provided docker compose files to start a local upstream service and identity provider. We suggest using httpbin as your upstream for testing as it allows for request and response introspection of all things HTTP.

Inside the contrib/local-environment directory you can use the Makefile for starting different example setups:

• Dex as your IdP: make up or make down
• Dex as your IdP using the alpha-config: make alpha-config-up
• Keycloak as your IdP: make keycloak-up
• Dex as your IdP & nginx reverse proxy: make nginx-up
• and many more...

Check out the Makefile to see what is available.

The username and password for all setups is usually [email protected] and password.

The docker compose setups expose the services with a dynamic reverse DNS resolver: localtest.me

• OAuth2-Proxy: http://oauth2-proxy.localtest.me:4180
• Upstream: http://httpbin.localtest.me:8080
• Dex: http://dex.localtest.me:4190