Skip to content

docs: replace the oauth2 experiment with CODER_OAUTH2_PROVIDER_ENABLE - #29268

Merged
BobbyHo merged 22 commits into
mainfrom
plat-492-5-docs
Sep 15, 2026
Merged

BobbyHo merged 22 commits into
mainfrom
plat-492-5-docs

Conversation

@BobbyHo

@BobbyHo BobbyHo commented Sep 12, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR

Last of five for PLAT-492. The docs no longer tell admins to enable the oauth2 experiment. The OAuth2 provider page, the MCP server page and the feature stages page show CODER_OAUTH2_PROVIDER_ENABLE instead.

PR What it does
#29248 Adds the flag, a public build info field, and the test default.
#29251 Gates the OAuth2 routes and dashboard navigation on the flag.
#29257 Removes the oauth2 experiment.
#29267 Logs the provider state and any registered apps at startup.
this Docs.

Changes
  • docs/admin/integrations/oauth2-provider.md: the title and callout drop "experimental". The Enable section shows the CLI flag, env var, YAML key and Helm coder.env forms. The troubleshooting entry becomes "OAuth2 endpoints return 404". The limitations and feedback sections drop the experimental framing.
  • docs/ai-coder/mcp-server.md: prerequisites become the flag plus CODER_EXPERIMENTS=mcp-server-http. The OAuth2 note and troubleshooting bullet name the flag.
  • docs/install/releases/feature-stages.md: one sentence in the GA section says a few GA features are off by default, naming the provider.
Release note draft

OAuth 2.1 provider is generally available and off by default. Set CODER_OAUTH2_PROVIDER_ENABLE=true to turn it on. The oauth2 experiment has been removed. Deployments that relied on CODER_EXPERIMENTS=oauth2 must set the new flag or their OAuth2 clients get 404 responses after upgrading. Setting the environment variable before upgrading is safe and avoids the gap; the old binary ignores it. Do not set the YAML key or the CLI flag before upgrading, because the old binary rejects both. On Kubernetes, set it through coder.env rather than coder.commandArgs, so pods on the old image keep starting. Existing OAuth2 applications, secrets and user authorizations are preserved and resume when the flag is set. Access tokens issued before the upgrade remain valid until they expire.

BobbyHo and others added 12 commits September 11, 2026 13:31
Add an opt-in deployment flag for Coder's OAuth 2.1 authorization server.
The flag is off by default and nothing reads it yet; a follow-up moves the
OAuth2 routes and dashboard navigation off the oauth2 experiment and onto
this flag.

- Add oauth2.provider.enable (--oauth2-provider-enable,
  CODER_OAUTH2_PROVIDER_ENABLE) under a new Provider group beneath OAuth2,
  and reword the OAuth2 group so it covers more than GitHub login.
- Add oauth2_provider to the build info response so the dashboard can read
  the provider state without an admin-only config request.
- Turn the flag on by default in coderdtest so existing OAuth2 tests keep
  working once the routes are gated on it.
- Regenerate API docs, TypeScript types, the CLI reference, and golden files.

Part of PLAT-492.
Read the build info flag value through api.DeploymentValues like the
neighbouring fields, and distinguish OAuth2ProviderConfig from
OAuth2ProviderSettings in its doc comment.
Move every OAuth2 provider gate off the oauth2 experiment and onto the
deployment flag added in the previous commit. The flag is off by default,
so a deployment that relied on CODER_EXPERIMENTS=oauth2 must set it or its
OAuth2 clients receive 404 responses after upgrading.

- Add httpmw.RequireOAuth2Provider, which answers 404 while the provider is
  disabled. A disabled provider looks like a deployment that never had one.
  There is no bypass for development builds.
- Use it on both discovery documents, the /oauth2 tree, the admin apps API,
  and the MCP HTTP endpoint, which keeps its mcp-server-http experiment
  check. The AI Gateway's deprecated MCP injection reads the flag too.
- Keep /api/v2/oauth2-provider/settings reachable while disabled so an
  admin can configure dynamic client registration before enabling the
  provider.
- Gate both OAuth2 navigation items on the new build info field instead of
  the experiment, and drop the development-build escape hatch.

The oauth2 experiment is still parsed and reported; a follow-up makes it a
no-op with a specific warning.

Part of PLAT-492.
RequireOAuth2Provider takes a bool: the flag is read once at startup in
three places, so the closure promised a runtime toggle that would ship
half-working. The settings comment moves onto the route it describes,
and both enabled sidebar stories set the flag explicitly instead of
relying on the fixture default.
The MCP HTTP endpoint no longer has a development-build bypass for the
mcp-server-http experiment, so tests that reach it must opt in.
…ER_ENABLE

The oauth2 experiment no longer does anything. ReadExperiments drops it
from the result and logs one warning per process naming the flag, so an
admin whose OAuth2 clients start getting 404s after upgrading sees why.
The constant stays known for one release so the warning can be specific;
the next release removes it.
The deprecation warning promised removal in the next release, which no
ticket backed. Removal is now tracked in PLAT-635, so the message says a
future release and the code comment names the ticket.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Trim the doc comment on the message constant to its purpose so it
cannot drift from the literal. Assert the deprecation warning by count
instead of an exact warn slice, which coupled the test to the safety
classification of an unrelated experiment, and check explicitly that no
unknown-experiment warning leaks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Every coder server start logs one info line stating whether the OAuth2
provider is enabled, naming CODER_OAUTH2_PROVIDER_ENABLE. When the
provider is disabled and applications are still registered, one warning
gives the count and the flag to set. A failed query is logged and does
not abort startup.

The SpammyLogs test allows two more rows for the new line.
The OAuth2 provider page, the MCP server page and the feature stages
page told admins to enable the oauth2 experiment, which no longer has
any effect. They now show CODER_OAUTH2_PROVIDER_ENABLE in CLI, env,
YAML and Helm forms, and the provider page drops the experimental
framing.
@linear-code

linear-code Bot commented Sep 12, 2026 •

Copy link
Copy Markdown

PLAT-492

DOCS-911

@github-actions

github-actions Bot commented Sep 12, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

Experiments carry no compatibility guarantee and previously graduated
experiments were deleted outright, so the oauth2 experiment goes the same
way. The constant, its display name, the known-list entry and the
recognized no-op branch in ReadExperiments are gone, along with the
once-per-process deprecation warning and its tests.

A leftover CODER_EXPERIMENTS=oauth2 value is now handled like any other
unknown experiment: the server logs "ignoring unknown experiment" and
nothing gates on it. The startup provider-state lines and the release
note carry the migration message pointing at CODER_OAUTH2_PROVIDER_ENABLE.
…moved

The callout said the experiment would be removed in a future release. It
is removed in this release.
BobbyHo added a commit that referenced this pull request Sep 14, 2026
…ENABLE (#29257)

Third of five for PLAT-492. Removes the oauth2 experiment entirely; CODER_EXPERIMENTS=oauth2 is now treated as an unknown experiment and nothing depends on it.

Stacked on #29251. No migration.
Removes ExperimentOAuth2 and its generated/API references.
Removed outright per review, consistent with experiments having no compatibility guarantee.
Migration guidance is covered by the startup logging in #29267 and docs/release notes in #29268, both pointing to CODER_OAUTH2_PROVIDER_ENABLE.
Existing unknown-experiment handling and tests already cover leftover oauth2 values.
After this merges, main is safe to cut a release from.
Base automatically changed from plat-492-4-startup-lines to main September 15, 2026 01:31
# Conflicts:
#	coderd/oauth2_provider_state.go
#	coderd/oauth2_provider_state_internal_test.go
@BobbyHo
BobbyHo marked this pull request as ready for review September 15, 2026 02:19
The admin UI hides the client secrets section for a public client, since
there is no secret to show or generate. State that alongside the rest of
the public client guidance.

@dylanhuff-at-coder dylanhuff-at-coder left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

overall lgtm, two non-blocking docs comments.

Comment thread docs/ai-coder/mcp-server.md Resolved
…er is off

Turning the provider off does not invalidate access tokens it already issued.
Those tokens keep authenticating to the regular Coder API while the OAuth2
refresh and revocation endpoints return 404, so the flag is not a substitute
for revoking an application's access.

Addresses reviewer feedback on the enable/disable section.
…equisites

The YAML and Helm pointer covered only the OAuth2 provider setting, leaving
YAML users without the top-level experiments key for mcp-server-http. Name
that scope and link the --experiments reference.
@BobbyHo
BobbyHo merged commit a031db8 into main Sep 15, 2026
29 checks passed
@BobbyHo
BobbyHo deleted the plat-492-5-docs branch September 15, 2026 16:15
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 15, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants