From 9945b68a06c32d5dbc4fc0dcaa150a93b509705e Mon Sep 17 00:00:00 2001 From: Jan Larwig Date: Sun, 27 Oct 2024 13:12:46 +0100 Subject: [PATCH] doc: readme overhaul and azure sponsorship (#2826) * new readme structure * add adopters file * add microsoft sponsorship * add reference to adopter file * add gopher slack invite link * slightly rephrase nightly image section * add sponsor request for action * better formatting for contributor wall * add longer wait time for stale PRs and issues and allow for exemption through bug and high-priority labels * apply review suggestion Co-authored-by: Joel Speed --------- Co-authored-by: Joel Speed --- .github/workflows/stale.yml | 8 +- ADOPTERS.md | 28 +++++ README.md | 114 ++++++++++--------- docs/docs/welcome.md | 2 +- docs/static/img/architecture.svg | 1 - docs/static/img/simplified-architecture.svg | 4 + docs/versioned_docs/version-7.6.x/welcome.md | 2 +- docs/versioned_docs/version-7.7.x/welcome.md | 2 +- 8 files changed, 102 insertions(+), 59 deletions(-) create mode 100644 ADOPTERS.md delete mode 100644 docs/static/img/architecture.svg create mode 100644 docs/static/img/simplified-architecture.svg diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 5df173b1..2406f695 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -13,5 +13,9 @@ jobs: - uses: actions/stale@v9 with: repo-token: ${{ secrets.GITHUB_TOKEN }} - stale-issue-message: 'This issue has been inactive for 60 days. If the issue is still relevant please comment to re-activate the issue. If no action is taken within 7 days, the issue will be marked closed.' - stale-pr-message: 'This pull request has been inactive for 60 days. If the pull request is still relevant please comment to re-activate the pull request. If no action is taken within 7 days, the pull request will be marked closed.' + days-before-stale: 180 + days-before-close: 14 + stale-issue-message: 'This issue has been inactive for 180 days. If the issue is still relevant please comment to re-activate the issue. If no action is taken within 14 days, the issue will be marked closed.' + stale-pr-message: 'This pull request has been inactive for 180 days. If the pull request is still relevant please comment to re-activate the pull request. If no action is taken within 14 days, the pull request will be marked closed.' + exempt-issue-labels: bug,high-priority + exempt-pr-labels: bug,high-priority diff --git a/ADOPTERS.md b/ADOPTERS.md new file mode 100644 index 00000000..b0a233e5 --- /dev/null +++ b/ADOPTERS.md @@ -0,0 +1,28 @@ +# Adopters + +This list showcases organizations that leverage OAuth2-Proxy within their +infrastructure. If your organization uses OAuth2-Proxy and isn't yet listed, we +encourage you to add it! + +This list aims to be a comprehensive and trusted resource for the OAuth2-Proxy +community, demonstrating successful adoption across all kinds of industries. + +Contributing to this list is a simple way to impact the project's growth, +maturity, and momentum. Thank you to all adopters and contributors of the +OAuth2-Proxy project! + +## Updating this list + +To add your organization to this list, you can just [open a PR](https://github.com/oauth2-proxy/oauth2-proxy/pulls) +to directly update this list. + +Add your organization name, your github username and if you desire a short +description on how you utilize oauth2-proxy. + +## OAuth2-Proxy Adopters + +This list is sorted in the order that organizations were added to it. + +| Organization | Contact | Description of Use | +| ------------ | ------- | ------------------ | +| | | | diff --git a/README.md b/README.md index 55eaec53..33849682 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -![OAuth2 Proxy](docs/static/img/logos/OAuth2_Proxy_horizontal.svg) - [![Continuous Integration](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yaml/badge.svg)](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yaml) [![Go Report Card](https://goreportcard.com/badge/github.com/oauth2-proxy/oauth2-proxy)](https://goreportcard.com/report/github.com/oauth2-proxy/oauth2-proxy) [![GoDoc](https://godoc.org/github.com/oauth2-proxy/oauth2-proxy?status.svg)](https://godoc.org/github.com/oauth2-proxy/oauth2-proxy) @@ -7,72 +5,82 @@ [![Maintainability](https://api.codeclimate.com/v1/badges/a58ff79407212e2beacb/maintainability)](https://codeclimate.com/github/oauth2-proxy/oauth2-proxy/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/a58ff79407212e2beacb/test_coverage)](https://codeclimate.com/github/oauth2-proxy/oauth2-proxy/test_coverage) -A reverse proxy and static file server that provides authentication using Providers (Google, Keycloak, GitHub and others) -to validate accounts by email, domain or group. +![OAuth2 Proxy](docs/static/img/logos/OAuth2_Proxy_horizontal.svg) -**Note:** This repository was forked from [bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy) on 27/11/2018. -Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork. -A list of changes can be seen in the [CHANGELOG](CHANGELOG.md). +OAuth2-Proxy is a flexible, open-source tool that can act as either a standalone reverse proxy or a middleware component integrated into existing reverse proxy or load balancer setups. It provides a simple and secure way to protect your web applications with OAuth2 / OIDC authentication. As a reverse proxy, it intercepts requests to your application and redirects users to an OAuth2 provider for authentication. As a middleware, it can be seamlessly integrated into your existing infrastructure to handle authentication for multiple applications. -**Note:** This project was formerly hosted as `pusher/oauth2_proxy` but has been renamed as of 29/03/2020 to `oauth2-proxy/oauth2-proxy`. -Going forward, all images shall be available at `quay.io/oauth2-proxy/oauth2-proxy` and binaries will be named `oauth2-proxy`. +OAuth2-Proxy supports a lot of OAuth2 as well as OIDC providers. Either through a generic OIDC client or a specific implementation for Google, Microsoft Entra ID, GitHub, login.gov and others. Through specialised provider implementations oauth2-proxy can extract more details about the user like preferred usernames and groups. Those details can then be forwarded as HTTP headers to your upstream applications. -![Sign In Page](docs/static/img/sign-in-page.png) +![Simplified Architecture](docs/static/img/simplified-architecture.svg) -## Installation +## Get Started -1. Choose how to deploy: +OAuth2-Proxy's [Installation Docs](https://oauth2-proxy.github.io/oauth2-proxy/installation) cover how to install and configure your setup. Additionally you can take a further look at the [example setup files](https://github.com/oauth2-proxy/oauth2-proxy/tree/master/contrib/local-environment). - a. Using a [Prebuilt Binary](https://github.com/oauth2-proxy/oauth2-proxy/releases) (current release is `v7.6.0`) +## Releases - b. Using Go to install the latest release - ```bash - $ go install github.com/oauth2-proxy/oauth2-proxy/v7@latest - ``` - This will install the binary into `$GOPATH/bin`. Make sure you include `$GOPATH` in your `$PATH`. Otherwise your system won't find binaries installed via `go install` +### Binaries +We publish oauth2-proxy as compiled binaries on GitHub for all major architectures as well as more exotic ones like `ppc64le` as well as `s390x`. - c. Using a [Prebuilt Docker Image](https://quay.io/oauth2-proxy/oauth2-proxy) (AMD64, PPC64LE, S390x, ARMv6, ARMv7, and ARM64 available) +Check out the [latest release](https://github.com/oauth2-proxy/oauth2-proxy/releases/latest). - d. Using a [Pre-Release Nightly Docker Image](https://quay.io/oauth2-proxy/oauth2-proxy-nightly) (AMD64, PPC64LE, S390x, ARMv6, ARMv7, and ARM64 available) - - e. Using the official [Kubernetes manifest](https://github.com/oauth2-proxy/manifests) (Helm) - - Prebuilt binaries can be validated by extracting the file and verifying it against the `sha256sum.txt` checksum file provided for each release starting with version `v3.0.0`. - - ``` - sha256sum -c sha256sum.txt 2>&1 | grep OK - oauth2-proxy-x.y.z.linux-amd64: OK - ``` - -2. [Select a Provider and Register an OAuth Application with a Provider](https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/) -3. [Configure OAuth2 Proxy using config file, command line options, or environment variables](https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview) -4. [Configure SSL or Deploy behind a SSL endpoint](https://oauth2-proxy.github.io/oauth2-proxy/configuration/tls) (example provided for Nginx) - - -## Security - -If you are running a version older than v6.0.0 we **strongly recommend you please update** to a current version. -See [open redirect vulnerability](https://github.com/oauth2-proxy/oauth2-proxy/security/advisories/GHSA-5m6c-jp6f-2vcv) for details. - -## Docs - -Read the docs on our [Docs site](https://oauth2-proxy.github.io/oauth2-proxy/). - -![OAuth2 Proxy Architecture](docs/static/img/architecture.svg) - -## Images +### Images From `v7.6.0` and up the base image has been changed from Alpine to [GoogleContainerTools/distroless](https://github.com/GoogleContainerTools/distroless). This image comes with even fewer installed dependencies and thus should improve security. The image therefore is also slightly smaller than Alpine. -For debugging purposes (and those who really need it (i.e. `armv6`)) we still provide images based on Alpine. The tags of these images are suffixed with `-alpine`. +For debugging purposes (and those who really need it. e.g. `armv6`) we still provide images based on Alpine. The tags of these images are suffixed with `-alpine`. -Since 2023-11-18 we provide nightly images. These images are build and pushed nightly to `quay.io/oauth2-proxy/oauth2-proxy-nightly` from `master`. -These images should be considered alpha and therefore *should not* be used for production purposes unless you know what you're doing. +Since 2023-11-18 we build nightly images directly from the `master` branch and provide them at `quay.io/oauth2-proxy/oauth2-proxy-nightly`. +These images are considered unstable and therefore should **NOT** be used for production purposes unless you know what you're doing. + +## Sponsors + +![Microsoft](https://upload.wikimedia.org/wikipedia/commons/9/96/Microsoft_logo_%282012%29.svg) +Microsoft Azure credits for open source projects + +Would you like to sponsor the project then please contact us at [sponsors@oauth2-proxy.dev](mailto:sponsors@oauth2-proxy.dev) ## Getting Involved +[![Slack](https://img.shields.io/badge/slack-Gopher_%23oauth2--proxy-red?logo=slack)](https://gophers.slack.com/archives/CM2RSS25N) -If you would like to reach out to the maintainers, come talk to us in the `#oauth2-proxy` channel in the [Gophers slack](http://gophers.slack.com/). +Join the #oauth2-proxy [Slack channel](https://gophers.slack.com/archives/CM2RSS25N) to chat with other users of oauth2-proxy or reach out to the maintainers directly. Use the [public invite link](https://invite.slack.golangbridge.org/) to get an invite for the Gopher Slack space. -## Contributing +OAuth2-Proxy is a community-driven project. We rely on the contribut️ions of our users to continually improve it. While review times can vary, we appreciate your patience and understanding. As a volunteer-driven project, we strive to keep this project stable and might take longer to merge changes. -Please see our [Contributing](CONTRIBUTING.md) guidelines. For releasing see our [release creation guide](RELEASE.md). +If you want to contribute to the project. Please see our [Contributing](https://oauth2-proxy.github.io/oauth2-proxy/community/contribution) guide. + +Who uses OAuth2-Proxy? Have a look at our new [ADOPTERS](ADOPTERS.md) file and +feel free to open a PR to add your organisation. + +Thanks to all the people who already contributed ❤ + + + + + + +Made with [contrib.rocks](https://contrib.rocks). + +## Security + +If you believe you have found a vulnerability within OAuth2 Proxy or any of its dependencies, please do **NOT** open an issue or PR on GitHub, please do **NOT** post any details publicly. + +Security disclosures **MUST** be done in private. If you have found an issue that you would like to bring to the attention of the maintainers, please compose an email and send it to the list of people listed in our [MAINTAINERS](MAINTAINERS) file. + +For more details read our full [Security Docs](https://oauth2-proxy.github.io/oauth2-proxy/community/security#security-disclosures) + +### Security Notice for v6.0.0 and older + +If you are running a version older than v6.0.0 we **strongly recommend** to the current version. + +See [open redirect vulnerability](https://github.com/oauth2-proxy/oauth2-proxy/security/advisories/GHSA-5m6c-jp6f-2vcv) for details. + +## Repository History + +**2018-11-27:** This repository was forked from [bitly/OAuth2_Proxy](https://github.com/bitly/oauth2_proxy). Versions v3.0.0 and up are from this fork and will have diverged from any changes in the original fork. A list of changes can be seen in the [CHANGELOG](CHANGELOG.md). + +**2020-03-29:** This project was formerly hosted as `pusher/oauth2_proxy` but has been renamed to `oauth2-proxy/oauth2-proxy`. Going forward, all images shall be available at `quay.io/oauth2-proxy/oauth2-proxy` and binaries will be named `oauth2-proxy`. + +## License + +OAuth2-Proxy is distributed under [The MIT License](LICENSE). diff --git a/docs/docs/welcome.md b/docs/docs/welcome.md index 4ee616d9..7bceadd8 100644 --- a/docs/docs/welcome.md +++ b/docs/docs/welcome.md @@ -20,4 +20,4 @@ A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy ## Architecture -![OAuth2 Proxy Architecture](/img/architecture.svg) +![OAuth2 Proxy Architecture](/img/simplified-architecture.svg) diff --git a/docs/static/img/architecture.svg b/docs/static/img/architecture.svg deleted file mode 100644 index 24e5d426..00000000 --- a/docs/static/img/architecture.svg +++ /dev/null @@ -1 +0,0 @@ -
nginx :443
(SSL Termination)
nginx :443...
oauth2-proxy
:4180
oauth2-proxy...
secured upstream
http service
secured upstream...
Auth Provider
(Google, Keycloak, ...)
Auth Provider...
oauth2-proxy
:443 (SSL)
oauth2-proxy...
secured upstream
http service
secured upstream...
Auth Provider
(Google, Keycloak, ...)
Auth Provider... \ No newline at end of file diff --git a/docs/static/img/simplified-architecture.svg b/docs/static/img/simplified-architecture.svg new file mode 100644 index 00000000..8cea8f91 --- /dev/null +++ b/docs/static/img/simplified-architecture.svg @@ -0,0 +1,4 @@ + + + +
OAuth2 Proxy as a standalone reverse-proxy
OAuth2 Proxy as a authentication middleware
Auth Provider
(Google, MS Entra, Keycloak, ...)
secured upstream
OAuth2_Proxy_logo_v3
Authenticate
Request
Forward authenticated requests
secured upstream
Request
Forward authenticated requests
OAuth2_Proxy_logo_v3
Authenticate
nginx
istio / envoy
traefik
Auth Provider
(Google, MS Entra, Keycloak, ...)
Request authentication
Respond with 200 or 401
 \ No newline at end of file diff --git a/docs/versioned_docs/version-7.6.x/welcome.md b/docs/versioned_docs/version-7.6.x/welcome.md index 4ee616d9..7bceadd8 100644 --- a/docs/versioned_docs/version-7.6.x/welcome.md +++ b/docs/versioned_docs/version-7.6.x/welcome.md @@ -20,4 +20,4 @@ A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy ## Architecture -![OAuth2 Proxy Architecture](/img/architecture.svg) +![OAuth2 Proxy Architecture](/img/simplified-architecture.svg) diff --git a/docs/versioned_docs/version-7.7.x/welcome.md b/docs/versioned_docs/version-7.7.x/welcome.md index 4ee616d9..7bceadd8 100644 --- a/docs/versioned_docs/version-7.7.x/welcome.md +++ b/docs/versioned_docs/version-7.7.x/welcome.md @@ -20,4 +20,4 @@ A list of changes can be seen in the [CHANGELOG](https://github.com/oauth2-proxy ## Architecture -![OAuth2 Proxy Architecture](/img/architecture.svg) +![OAuth2 Proxy Architecture](/img/simplified-architecture.svg)