diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 596b4aaf..4912d9c5 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,5 +1,31 @@ -# Default owner should be a core org reviewers unless overridden by later rules in this file -* @oauth2-proxy/reviewers +# OAuth2-Proxy CODEOWNERS +# This file maps repository paths to GitHub teams for review. +# Syntax: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# --- Core Maintainers (project-wide) --- +* @oauth2-proxy/maintainers + +# --- Core --- +* @oauth2-proxy/core-reviewers + +# --- Documentation --- +docs/ @oauth2-proxy/documentation-reviewers + +# --- CI / Testing --- +.devcontainer/ @oauth2-proxy/ci-reviewers +.github/ @oauth2-proxy/ci-reviewers +.vscode/ @oauth2-proxy/ci-reviewers +contrib/ @oauth2-proxy/ci-reviewers +go.mod @oauth2-proxy/ci-reviewers +go.sum @oauth2-proxy/ci-reviewers + +# --- Configuration / API --- +contrib/ @oauth2-proxy/api-reviewers +pkg/apis/ @oauth2-proxy/api-reviewers + + +# --- Provider --- +providers/ @oauth2-proxy/provider-reviewers # login.gov provider # Note: If @timothy-spencer terms out of his appointment, your best bet @@ -7,17 +33,4 @@ # in the login.gov team (https://login.gov/developers/), the cloud.gov team # (https://cloud.gov/docs/help/), or the 18F org (https://18f.gsa.gov/contact/ # or the public devops channel at https://chat.18f.gov/). -providers/logingov.go @timothy-spencer -providers/logingov_test.go @timothy-spencer - -# Bitbucket provider -providers/bitbucket.go @aledeganopix4d -providers/bitbucket_test.go @aledeganopix4d - -# Nextcloud provider -providers/nextcloud.go @Ramblurr -providers/nextcloud_test.go @Ramblurr - -# DigitalOcean provider -providers/digitalocean.go @kamaln7 -providers/digitalocean_test.go @kamaln7 +providers/logingov.* @oauth2-proxy/provider-login-gov-reviewers diff --git a/CONTRIBUTOR_LADDER.md b/CONTRIBUTOR_LADDER.md new file mode 100644 index 00000000..565885e8 --- /dev/null +++ b/CONTRIBUTOR_LADDER.md @@ -0,0 +1,268 @@ +# OAuth2-Proxy Contributor Ladder + +This document defines the roles, responsibilities, advancement criteria, +inactivity process, and interim role policies for OAuth2-Proxy contributors. +It extends the standard Kubernetes-style ladder with **specialty tracks** so +contributors can grow within their focus areas. + +--- + +## Roles + +### 1) Contributor +Anyone making contributions of any kind (code, docs, tests, CI configs, security +reports, reviews, triage, discussions). + +**Requirements** +- For code changes all commits need to be Signed-Off by you. This is enforced + through the [DCO GitHub App](https://github.com/apps/dco) +- Follow the OAuth2-Proxy/CNCF [Code of Conduct](CODE_OF_CONDUCT.md) + +**Privileges** +- Recognized as an active community member +- Eligible for nomination to **Member** + +--- + +### 2) Member +Regular contributors engaged with the project for at least **3 months**. + +**Requirements** +- Self nomination by the contributor via a GitHub Issue. +- Must be Sponsored/Approved by **two Core Maintainers** (sponsorship ask must + happen within the GitHub issue by tagging the sponsors). +- Substantive contributions (code, docs, tests, reviews, triage) in the last + 3 months. + +**Privileges** +- Added to the GitHub `members` team. +- Can be assigned issues and PRs. +- Eligible for **Reviewer** nomination. + +--- + +### 3) Reviewer (per Specialty) +Experienced contributors who review changes in **one or more specialties**. + +**Requirements** +- Member for at least **3 months**. +- Regular, high-quality reviews in the specialty. +- Several meaningful Issue or PR reviews over the last 3 months. + +**Privileges** +- Listed as `reviewer` in the relevant `OWNERS` files. +- May use `/lgtm` on PRs within the specialty. +- Eligible for **Maintainer** nomination. + +> A contributor may hold different roles across specialties + (e.g., **Reviewer** in Provider Integrations, **Member** in Core Proxy). + +--- + +### 4) Maintainer (Project-Wide) +Project leaders with governance, release, and cross-specialty responsibility. + +**Requirements** +- Reviewer for at least **6 months** in one or more specialties. +- Demonstrated leadership, reliability, and constructive collaboration. +- Nominated and approved by a **simple majority** of Maintainers. + +**Privileges** +- GitHub admin rights as needed. +- Release management authority. +- Representation within CNCF. + +--- + +## Specialty Tracks + +Specialties define scope for `reviewer` permissions and expectations. + +### Core Proxy +Focus: Main proxy functionality, request handling, session management, +authentication flow, and security implementation. + +**Key Responsibilities:** +- Review core proxy changes in files like `oauthproxy.go`, `main.go`, and `validator.go` +- Ensure adherence to [OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749) + and [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) specifications +- Validate security implementations, including session management, token + validation, and secure cookie handling +- Review authentication and authorization flow implementations +- Ensure proper handling of edge cases and security vulnerabilities + +### Provider Integrations +Focus: OAuth/OIDC provider integrations in the `providers/` directory. + +**Key Responsibilities:** +- Review provider-specific code changes in the `providers/` directory +- Ensure conformance to OAuth/OIDC standards and provider-specific requirements +- Coordinate breaking changes for provider implementations +- Review provider configuration documentation +- Validate provider test implementations + +### Configuration / API +Focus: Configuration options, API changes, and example configurations. + +**Key Responsibilities:** +- Review configuration-related code and documentation +- Ensure backward compatibility of configuration options +- Review example configurations in the `contrib/` directory +- Validate CLI argument parsing and validation + +### Helm Chart & Kubernetes +Focus: Helm chart in the separate `oauth2-proxy/manifests` repository and +Kubernetes deployment configurations. + +**Key Responsibilities:** +- Review Helm chart templates and values +- Ensure Kubernetes best practices in deployment configurations +- Validate Helm chart testing and CI integration +- Review Kubernetes-related documentation + +### Documentation +Focus: Documentation in the `docs/` directory, including configuration guides, +provider documentation, and tutorials. + +**Key Responsibilities:** +- Review documentation changes for accuracy and clarity +- Ensure documentation is kept in sync with code changes +- Review provider-specific documentation +- Validate example configurations and tutorials +- Review versioning and release documentation + +### CI / Automation +Focus: Test implementations and CI/CD workflows across repositories. + +**Key Responsibilities:** +- Review integration and E2E tests +- Ensure adequate test coverage for new features +- Review CI/CD workflows in `.github/workflows/` +- Validate test infrastructure and test data +- Review test automation and reporting + +### Community +Focus: Community nurturing, issue triage, and user support. + +**Key Responsibilities:** +- Help with issue triage and support requests +- Monitor community channels (Slack, GitHub Discussions) +- Organize community talks and events +- Promote OAuth2-Proxy in the community +- Create demos and tutorials for users +- Foster a welcoming environment for new contributors + +--- + +### Specialty Advancement + +Contributors can advance in multiple specialties simultaneously. For example: + +- A contributor could be a **Reviewer** in Provider Integrations and a **Member** in Core Proxy +- A contributor could be a **Reviewer** in both Helm Chart & Kubernetes and Testing & CI + +This allows contributors to focus on areas where they have expertise while still contributing to other parts of the project. + + +--- + +## Member Abuse + +Abuse of project resources is a serious violation of our community standards and +will not be tolerated. This includes but is not limited to: + +* Using project infrastructure for unauthorized activities. +* Misusing project funds or financial resources. +* Gaining unauthorized access to or damaging project infrastructure. +* Willingly engaging in activities that are against the Code of Conduct. +* Willingly introducing malware or viruses to the project's infrastructure or codebase. +* Any other activity that jeopardizes the project's resources, reputation, or community members. + +### Procedure for Handling Abuse + +1. **Immediate Revocation of Privileges**: If abuse is suspected, any maintainer + can immediately revoke the member's access to all project infrastructure and + resources to prevent further damage. This is a precautionary measure and not a + final judgment. + +2. **Investigation**: The maintainers will conduct a private investigation to + gather all relevant facts and evidence. The accused member will be given an + opportunity to respond to the allegations. + +3. **Decision**: Based on the investigation, the maintainers will determine if a + violation has occurred. + +4. **Consequences**: If a violation is confirmed, consequences will be applied, + which may include: + - Permanent removal from the project. + - Reporting the user to GitHub and other relevant platforms. + - In cases of financial misuse or illegal activities, reporting to law + enforcement authorities. + +All actions taken will be documented. The privacy of all individuals involved +will be respected throughout the process. + +--- + +## Advancement Process + +1. **Nomination** by an eligible community member (Member or Higher) via a GitHub issue. +2. **Sponsorship** by two role holders at the **target level or higher** (within the specialty where applicable). +3. **Review** of activity and behavior (quality, reliability, collaboration, responsiveness). +4. **Decision** by lazy consensus of the relevant group (or **simple majority** if contested). + +--- + +## Inactivity + +A **Reviewer** or **Maintainer** role holder may be considered inactive if they +have not actively contributed or performed general project responsibilities for +**six (6) consecutive months**. + +### Measurement Sources +- GitHub activity: Merged PRs, PR reviews, issue triage/comments. +- Participation in community calls or asynchronous design discussions. + +### Triggering Process +1. **Detection** + - Activity is reviewed at least quarterly by Maintainers or via automation. + - Any Maintainer may propose an inactivity review for a role holder. +2. **Notification** + - A public issue is opened in a `community`/`governance` space (or email if sensitive). + - The individual is tagged/emailed and given **30 days** to respond. +3. **Grace Period** + - If the contributor indicates intent to return, no change is made. + - If there is no response within the grace period, proceed. +4. **Decision** + - Demotion is decided by **lazy consensus** of Maintainers, or **simple majority** if contested. +5. **Scope** + - Demotion via inactivity fully removes the role holder from the organization. +6. **Documentation** + - Update `OWNERS`, GitHub teams, and governance records. + - Former Members may be listed as **Emeritus**. + +### Reinstatement +A contributor can be reinstated at their previous level via the standard +advancement process. Prior history is considered favorably. + +--- + +## Emeritus Status +Emeritus status recognizes former Maintainers, Reviewers, or Members who have +made substantial and lasting contributions to the OAuth2-Proxy project but are +stepping down from active responsibilities. + +Emeritus status is honorary and does not confer any formal responsibilities or +authority. + +### Purpose +* Honor and recognize long-term contributions. +* Preserve institutional knowledge and mentorship potential. +* Encourage continued engagement with the community without requiring full role responsibilities. + +--- + +## Cross-References + +- Project governance and decision-making: see [GOVERNANCE.md](GOVERNANCE.md) +- Specialty ownership: [CODEOWNERS](./.github/CODEOWNERS) files per directory diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000..e3917a44 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,170 @@ +# OAuth2-Proxy Governance + +This document defines the project governance for OAuth2-Proxy + +## Overview + +**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. + +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. + +## Community Roles + +- **Users**: Engineers and operators who deploy, configure, and maintain + OAuth2-Proxy in their environments. These are typically DevOps engineers, + SREs, or platform engineers who integrate OAuth2-Proxy with their + applications. End users who authenticate through OAuth2-Proxy typically do + not interact directly with OAuth2-Proxy +- **Contributors**: Anyone who makes contributions (code, docs, tests, reviews, + triage, discussions) +- **Reviewers / Maintainers**: Governance roles with defined responsibilities, + privileges, and promotion processes described in the [Contributor Ladder](CONTRIBUTOR_LADDER.md) + +Maintainers are project leaders responsible for overall health, technical +direction, and release management. + +--- + +## Maintainers + +### Core Maintainers +Core Maintainers are a subset of Maintainers who have been with the project for +an extended period and have demonstrated consistent technical leadership and +commitment. They are responsible for major project decisions, including +governance changes and maintainer appointments. + +### Expectations +Maintainers are expected to: +- Review pull requests, triage issues, and fix bugs in their areas of expertise +- Monitor community channels and help users and contributors +- Respond to time-sensitive security issues +- Follow the decision-making processes described in this document and in the + Contributor Ladder + +If a maintainer cannot fulfill these duties, they should move to **Emeritus** +status. Maintainers may also be moved to Emeritus via the decision-making process. + +### Adding or Removing Maintainers +- **Addition**: A candidate is nominated by an existing maintainer and elected + by a **simple majority** of current maintainers +- **Removal**: Removal requires a **simple majority** of current maintainers +- **Company voting**: Votes to nominate maintainers by contributors belonging + to the same employer count as **one** collective vote. + +--- + +## Voting Eligibility + +Voting rights vary by decision type: + +| Decision Type | Eligible Voters | +|------------------------------------------------|----------------------------------------------| +| **Governance changes** | Core Maintainers | +| **Adding/removing Maintainers** | Core Maintainers | +| **Technical decisions within a specialty** | All Reviewers and Maintainers | +| **Project-wide technical direction** | All Maintainers | +| **Security incident decisions** | All Maintainers | + +**Notes:** +- Company voting limits apply: maintainers/reviewers from the same declared + employer have **one** combined vote +- If maintainers/reviewers from the same declared employer cannot reach + consensus for their vote, that employer's vote is recorded as **abstain** + +--- + +## Decision Making + +OAuth2-Proxy strives for **consensus** via open discussion. When consensus +cannot be reached, any eligible voter may call a vote. + +- **Simple Majority**: More than 50% of eligible voters in the group +- **Venues**: Votes may occur on GitHub, email, Slack, community meetings, or a + suitable voting service +- **Ballots**: "Agree/+1", "Disagree/-1", or "Abstain" (counts as no vote) + +--- + +## Contributing Changes + +The process of reviewing proposed changes differs depending on the size and +impact of the change. + +### Minor Changes +A minor change is a bug fix, a smaller enhancement or a smaller addition to +existing features. + +To propose a minor change, simply create an issue in our [Issue Tracker](https://github.com/oauth2-proxy/oauth2-proxy/issues) or directly create a pull request. + +A maintainer will be responsible for ultimately approving the pull request. The +maintainer may do a deep review of the pull request or delegate to an expert in +the corresponding area. + +If the change has a bigger impact it has to follow the process for larger +changes. + +### Larger Changes +For larger changes all maintainers and contributors should have a chance of +reviewing the change. Therefore larger changes require an RFC to be created +through the [Issue Tracker](https://github.com/oauth2-proxy/oauth2-proxy/issues). + +If there are any objections to the change they can in most cases be resolved +through discussions in the corresponding issue or pull request. If a resolution +can not be made it can be accepted if at least 2/3 of maintainers approve the +change. + +--- + +## Lazy Consensus + +OAuth2-Proxy uses [Lazy Consensus](http://en.osswiki.info/concepts/lazy_consensus) for most decisions. + +- PRs and proposals should allow **at least eight (8) working days** for comments +- Other maintainers may request additional time when justified and commit to a + timely review + +**Exclusions** (lazy consensus does **not** apply): +- Removal of maintainers +- Any substantive governance changes + +--- + +## Updating Governance + +Substantive changes to this document require a **simple majority** of Core Maintainers. + +--- + +## Contributor Pathways & Specialties + +Advancement pathways, responsibilities, privileges, and specialty areas are +defined in the [Contributor Ladder](CONTRIBUTOR_LADDER.md). + +--- + +## Security + +OAuth2-Proxy follows responsible disclosure practices. Security-impacting +issues should be reported via the documented security contact channels +(see `SECURITY.md` if present or repository Security tab). Security fixes may +be handled privately until a coordinated disclosure and release are ready. + +--- + +## CNCF Alignment + +OAuth2-Proxy governance aims for open, transparent, and vendor-neutral operation +consistent with CNCF expectations. The [Contributor Ladder](CONTRIBUTOR_LADDER.md) +provides clear pathways for community members to grow into leadership. diff --git a/MAINTAINERS b/MAINTAINERS deleted file mode 100644 index f54915e9..00000000 --- a/MAINTAINERS +++ /dev/null @@ -1,5 +0,0 @@ -Joel Speed (@JoelSpeed) -Nick Meves (@NickMeves) -Braunson (@braunsonm) -Jan Larwig (@tuunit) -Koen van Zuijlen (@kvanzuijlen) diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 00000000..71ec0fdc --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,33 @@ +# Maintainers + +The table below lists all current maintainers for the oauth2-proxy as defined +by our [project governance](GOVERNANCE.md). + +| Name | GitHub Handle | Domains of reponsibility | Email Alias | Affiliation | +| ---------------- | ------------------------------------------------------ | ------------------------ | -------------------------- | ----------- | +| Joel Speed | [@JoelSpeed](https://github.com/joelspeed) | Governance, Core | joel@oauth2-proxy.dev | Red Hat | +| Jan Larwig | [@tuunit](https://github.com/tuunit) | Governance, Core | jan@oauth2-proxy.dev | IONOS Cloud | +| JJ Łakis | [@jjlakis](https://github.com/jjlakis) | Provider | jj@oauth2-proxy.dev | - | +| Koen van Zuijlen | [@kvanzuijlen](https://github.com/kvanzuijlen) | CI | koen@oauth2-proxy.dev | - | +| Pierluigi Lenoci | [@pierluigilenoci](https://github.com/pierluigilenoci) | Helm | pierluigi@oauth2-proxy.dev | SAP | + +## Emeritus Maintainers + +We would like to highlight that this project does have prior maintainers and +core contributors that, if they so wished, could (and should) be granted the +status of emeritus maintainers. + +| Name | GitHub Handle | +| ------------- | ------------------------------------------------------ | +| Nick Meves | [@NickMeves](https://github.com/NickMeves) | +| Braunson | [@braunsonm](https://github.com/braunsonm) | +| Henry Jenkins | [@steakunderscore](https://github.com/steakunderscore) | + + +## Security Response Team and GitHub Organization Owners + +The following maintainers are members of the security response team and owners +of the GitHub organization. + +- Joel Speed +- Jan Larwig