diff --git a/contrib/local-environment/dex.yaml b/contrib/local-environment/dex.yaml index ae687e05..fd64152b 100644 --- a/contrib/local-environment/dex.yaml +++ b/contrib/local-environment/dex.yaml @@ -1,7 +1,7 @@ # This configuration is intended to be used with the docker-compose testing # environment. # This should configure Dex to run on port 4190 and provides a static login -issuer: http://dex.localhost:4190/dex +issuer: http://dex.localtest.me:4190/dex storage: type: etcd config: @@ -19,7 +19,7 @@ staticClients: - id: oauth2-proxy redirectURIs: # These redirect URIs point to the `--redirect-url` for OAuth2 proxy. - - 'http://localhost:4180/oauth2/callback' # For basic proxy example. + - 'http://oauth2-proxy.localtest.me:4180/oauth2/callback' # For basic proxy example. - 'http://oauth2-proxy.oauth2-proxy.localhost/oauth2/callback' # For nginx and traefik example. name: 'OAuth2 Proxy' secret: b2F1dGgyLXByb3h5LWNsaWVudC1zZWNyZXQK diff --git a/contrib/local-environment/docker-compose-keycloak.yaml b/contrib/local-environment/docker-compose-keycloak.yaml index e9dfa17e..ae435ea3 100644 --- a/contrib/local-environment/docker-compose-keycloak.yaml +++ b/contrib/local-environment/docker-compose-keycloak.yaml @@ -12,7 +12,6 @@ # Access http://keycloak.localtest.me:9080 with the same credentials to check out the settings version: '3.0' services: - oauth2-proxy: container_name: oauth2-proxy image: quay.io/oauth2-proxy/oauth2-proxy:v7.5.1 @@ -21,6 +20,8 @@ services: volumes: - "./oauth2-proxy-keycloak.cfg:/oauth2-proxy.cfg" restart: unless-stopped + ports: + - 4180:4180/tcp networks: keycloak: {} httpbin: {} @@ -28,15 +29,17 @@ services: depends_on: - httpbin - keycloak - ports: - - 4180:4180/tcp httpbin: container_name: httpbin image: kennethreitz/httpbin:latest hostname: httpbin + ports: + - 8080:80/tcp networks: - httpbin: {} + httpbin: + aliases: + - httpbin.localtest.me keycloak: container_name: keycloak @@ -50,19 +53,19 @@ services: '-Dkeycloak.migration.action=import', '-Dkeycloak.migration.provider=dir', '-Dkeycloak.migration.dir=/realm-config', - '-Dkeycloak.migration.strategy=IGNORE_EXISTING', + '-Dkeycloak.migration.strategy=IGNORE_EXISTING' ] volumes: - ./keycloak:/realm-config environment: KEYCLOAK_USER: admin@example.com KEYCLOAK_PASSWORD: password + ports: + - 9080:9080/tcp networks: keycloak: aliases: - keycloak.localtest.me - ports: - - 9080:9080/tcp networks: httpbin: {} diff --git a/contrib/local-environment/docker-compose.yaml b/contrib/local-environment/docker-compose.yaml index c5ba9ecf..52cf786a 100644 --- a/contrib/local-environment/docker-compose.yaml +++ b/contrib/local-environment/docker-compose.yaml @@ -8,19 +8,19 @@ # Or: # make (eg. make up, make down) # -# Access http://localhost:4180 to initiate a login cycle +# Access http://oauth2-proxy.localtest.me:4180 to initiate a login cycle version: '3.0' services: oauth2-proxy: container_name: oauth2-proxy image: quay.io/oauth2-proxy/oauth2-proxy:v7.5.1 command: --config /oauth2-proxy.cfg - ports: - - 4180:4180/tcp hostname: oauth2-proxy volumes: - "./oauth2-proxy.cfg:/oauth2-proxy.cfg" restart: unless-stopped + ports: + - 4180:4180/tcp networks: dex: {} httpbin: {} @@ -31,16 +31,16 @@ services: container_name: dex image: ghcr.io/dexidp/dex:v2.30.3 command: dex serve /dex.yaml - ports: - - 4190:4190/tcp hostname: dex volumes: - "./dex.yaml:/dex.yaml" restart: unless-stopped + ports: + - 4190:4190/tcp networks: dex: aliases: - - dex.localhost + - dex.localtest.me etcd: {} depends_on: - etcd @@ -50,7 +50,9 @@ services: ports: - 8080:80/tcp networks: - httpbin: {} + httpbin: + aliases: + - httpbin.localtest.me etcd: container_name: etcd image: gcr.io/etcd-development/etcd:v3.4.7 diff --git a/contrib/local-environment/oauth2-proxy-keycloak.cfg b/contrib/local-environment/oauth2-proxy-keycloak.cfg index 6620b8ad..602cf312 100644 --- a/contrib/local-environment/oauth2-proxy-keycloak.cfg +++ b/contrib/local-environment/oauth2-proxy-keycloak.cfg @@ -1,8 +1,8 @@ http_address="0.0.0.0:4180" cookie_secret="OQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w=" -email_domains=["example.com"] +email_domains="example.com" cookie_secure="false" -upstreams="http://httpbin" +upstreams="http://httpbin.localtest.me:8080" cookie_domains=[".localtest.me"] # Required so cookie can be read on all subdomains. whitelist_domains=[".localtest.me"] # Required to allow redirection back to original requested target. @@ -16,5 +16,3 @@ redirect_url="http://oauth2-proxy.localtest.me:4180/oauth2/callback" oidc_issuer_url="http://keycloak.localtest.me:9080/auth/realms/master" provider="oidc" provider_display_name="Keycloak" - - diff --git a/contrib/local-environment/oauth2-proxy.cfg b/contrib/local-environment/oauth2-proxy.cfg index 7ee55d8f..ee58e145 100644 --- a/contrib/local-environment/oauth2-proxy.cfg +++ b/contrib/local-environment/oauth2-proxy.cfg @@ -1,11 +1,16 @@ http_address="0.0.0.0:4180" cookie_secret="OQINaROshtE9TcZkNAm-5Zs2Pv3xaWytBmc5W7sPX7w=" -provider="oidc" email_domains="example.com" -oidc_issuer_url="http://dex.localhost:4190/dex" +cookie_secure="false" +upstreams="http://httpbin.localtest.me:8080" +cookie_domains=[".localtest.me"] # Required so cookie can be read on all subdomains. +whitelist_domains=[".localtest.me"] # Required to allow redirection back to original requested target. + +# dex provider client_secret="b2F1dGgyLXByb3h5LWNsaWVudC1zZWNyZXQK" client_id="oauth2-proxy" -cookie_secure="false" +redirect_url="http://oauth2-proxy.localtest.me:4180/oauth2/callback" -redirect_url="http://localhost:4180/oauth2/callback" -upstreams="http://httpbin" +oidc_issuer_url="http://dex.localtest.me:4190/dex" +provider="oidc" +provider_display_name="Dex" diff --git a/docs/docs/community/contribution.md b/docs/docs/community/contribution.md new file mode 100644 index 00000000..cb0b2846 --- /dev/null +++ b/docs/docs/community/contribution.md @@ -0,0 +1,78 @@ +--- +id: contribution +title: Contribution Guide +--- + +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](https://code.visualstudio.com/docs/languages/go) with the official [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.go) extension. + + +# Go version + +This project is currently still using go 1.19. You can follow the installation guide for go [here.](https://go.dev/doc/install) And you can find go version 1.19 in the archived section [here.](https://go.dev/dl/) + +# Preparing your fork +Clone your fork, create a feature branch and update the depedencies to get started. +```bash +git clone git@github.com:/oauth2-proxy +cd oauth2-proxy +git branch feature/ +git push --set-upstream origin feature/ +go mod download +``` + + +# Testing / Debugging +For starting oauth2-proxy locally open the debugging tab and create the `launch.json` and select `Go: Launch Package`. + +![Debugging Tab](/img/debug-tab.png) +```json +{ + "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](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP. + +Open a terminal and switch to the `contrib/local-environment` directory. + +- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin` +- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin` + +The username for both is `admin@example.com` and password is `password`. + +Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing. diff --git a/docs/sidebars.js b/docs/sidebars.js index b573ad5e..a73d7ae1 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -67,7 +67,7 @@ module.exports = { id: 'community/security', }, collapsed: false, - items: ['community/security'], + items: ['community/contribution', 'community/security'], }, ], }; diff --git a/docs/src/pages/index.md b/docs/src/pages/index.md index b75b4e24..e08e3450 100644 --- a/docs/src/pages/index.md +++ b/docs/src/pages/index.md @@ -14,8 +14,8 @@ Versions v3.0.0 and up are from this fork and will have diverged from any change A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/CHANGELOG.md). ::: -![Sign In Page](../../static/img/sign-in-page.png) +![Sign In Page](/img/sign-in-page.png) ## Architecture -![OAuth2 Proxy Architecture](../../static/img/architecture.png) +![OAuth2 Proxy Architecture](/img/architecture.png) diff --git a/docs/static/img/debug-tab.png b/docs/static/img/debug-tab.png new file mode 100644 index 00000000..dfa79baa Binary files /dev/null and b/docs/static/img/debug-tab.png differ diff --git a/docs/versioned_docs/version-7.5.x/community/contribution.md b/docs/versioned_docs/version-7.5.x/community/contribution.md new file mode 100644 index 00000000..cb0b2846 --- /dev/null +++ b/docs/versioned_docs/version-7.5.x/community/contribution.md @@ -0,0 +1,78 @@ +--- +id: contribution +title: Contribution Guide +--- + +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](https://code.visualstudio.com/docs/languages/go) with the official [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=golang.go) extension. + + +# Go version + +This project is currently still using go 1.19. You can follow the installation guide for go [here.](https://go.dev/doc/install) And you can find go version 1.19 in the archived section [here.](https://go.dev/dl/) + +# Preparing your fork +Clone your fork, create a feature branch and update the depedencies to get started. +```bash +git clone git@github.com:/oauth2-proxy +cd oauth2-proxy +git branch feature/ +git push --set-upstream origin feature/ +go mod download +``` + + +# Testing / Debugging +For starting oauth2-proxy locally open the debugging tab and create the `launch.json` and select `Go: Launch Package`. + +![Debugging Tab](/img/debug-tab.png) +```json +{ + "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](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP. + +Open a terminal and switch to the `contrib/local-environment` directory. + +- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin` +- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin` + +The username for both is `admin@example.com` and password is `password`. + +Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing. diff --git a/docs/versioned_sidebars/version-7.5.x-sidebars.json b/docs/versioned_sidebars/version-7.5.x-sidebars.json index b52d71a3..6141da25 100644 --- a/docs/versioned_sidebars/version-7.5.x-sidebars.json +++ b/docs/versioned_sidebars/version-7.5.x-sidebars.json @@ -33,6 +33,7 @@ "label": "Community", "collapsed": false, "items": [ + "community/contribution", "community/security" ] }