From 524cfb9cb95b0661b142e7c2d9b7c6c237a03760 Mon Sep 17 00:00:00 2001 From: Bobby Ho Date: Sat, 12 Sep 2026 10:51:16 -0700 Subject: [PATCH 1/2] docs: replace the oauth2 experiment with CODER_OAUTH2_PROVIDER_ENABLE 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. --- docs/admin/integrations/oauth2-provider.md | 54 ++++++++++++++-------- docs/ai-coder/mcp-server.md | 16 ++++--- docs/install/releases/feature-stages.md | 6 +-- 3 files changed, 48 insertions(+), 28 deletions(-) diff --git a/docs/admin/integrations/oauth2-provider.md b/docs/admin/integrations/oauth2-provider.md index 66f7c996e1f..af594baa49c 100644 --- a/docs/admin/integrations/oauth2-provider.md +++ b/docs/admin/integrations/oauth2-provider.md @@ -1,39 +1,55 @@ --- -title: OAuth2 provider (Experimental) +title: OAuth2 provider --- -> [!WARNING] -> The OAuth2 provider functionality is currently **experimental and unstable**. This feature: -> -> - Is subject to breaking changes without notice -> - May have incomplete functionality -> - Is not recommended for production use -> - Requires the `oauth2` experiment flag to be enabled -> -> Use this feature for development and testing purposes only. +> [!NOTE] +> The OAuth2 provider is generally available and off by default. +> Set `CODER_OAUTH2_PROVIDER_ENABLE=true` to turn it on. +> The `oauth2` experiment no longer has any effect and will be removed in a future release. Coder can act as an OAuth2 authorization server, allowing third-party applications to authenticate users through Coder and access the Coder API on their behalf. This enables integrations where external applications can leverage Coder's authentication and user management. ## Requirements - Admin privileges in Coder -- OAuth2 experiment flag enabled +- `CODER_OAUTH2_PROVIDER_ENABLE=true` set on the Coder server - HTTPS recommended for production deployments ## Enable OAuth2 Provider -Add the `oauth2` experiment flag to your Coder server: +The provider is off by default. +While it is off, the OAuth2 endpoints and discovery documents return 404 and the **OAuth2 Applications** page is hidden. +Turn it on with the CLI flag: ```sh -coder server --experiments oauth2 +coder server --oauth2-provider-enable ``` Or set the environment variable: ```dotenv -CODER_EXPERIMENTS=oauth2 +CODER_OAUTH2_PROVIDER_ENABLE=true +``` + +Or set it in the YAML configuration file: + +```yaml +oauth2: + provider: + enable: true ``` +For Kubernetes deployments that use the Helm chart, add the environment variable to `coder.env` in your values file: + +```yaml +coder: + env: + - name: CODER_OAUTH2_PROVIDER_ENABLE + value: "true" +``` + +Existing applications, secrets, and user authorizations are kept while the provider is off and work again when you turn it on. + ## Creating OAuth2 Applications ### Method 1: Web UI @@ -396,9 +412,11 @@ For more details on testing, see the [OAuth2 test scripts README](../../../scrip ## Common Issues -### "OAuth2 experiment not enabled" +### OAuth2 endpoints return 404 -Add `oauth2` to your experiment flags: `coder server --experiments oauth2` +The provider is off. +Set `CODER_OAUTH2_PROVIDER_ENABLE=true` and restart the server. +Refer to [Enable OAuth2 Provider](#enable-oauth2-provider). ### "Invalid redirect_uri" @@ -640,7 +658,7 @@ Public clients (`token_endpoint_auth_method: none`) additionally cannot register ## Limitations -As an experimental feature, the current implementation has limitations: +The current implementation has these limitations: - A scope allowlist can only be declared at [Dynamic Client Registration](#dynamic-client-registration); applications created through the web UI or the management API cannot restrict which scopes a client may request - No client credentials grant support @@ -694,4 +712,4 @@ pages. ## Feedback -This is an experimental feature under active development. Please report issues and feedback through [GitHub Issues](https://github.com/coder/coder/issues) with the `oauth2` label. +Report issues and feedback through [GitHub Issues](https://github.com/coder/coder/issues) with the `oauth2` label. diff --git a/docs/ai-coder/mcp-server.md b/docs/ai-coder/mcp-server.md index 0dc30435b68..49a4f3223e6 100644 --- a/docs/ai-coder/mcp-server.md +++ b/docs/ai-coder/mcp-server.md @@ -101,19 +101,21 @@ implemented. ### Prerequisites -The remote MCP HTTP endpoint requires both the `oauth2` and `mcp-server-http` -experiments enabled on your Coder deployment: +The remote MCP HTTP endpoint requires the OAuth2 provider and the `mcp-server-http` experiment on your Coder deployment: ```sh -coder server --experiments=oauth2,mcp-server-http +coder server --oauth2-provider-enable --experiments=mcp-server-http ``` -Or set the environment variable: +Or set the environment variables: ```sh -CODER_EXPERIMENTS=oauth2,mcp-server-http +CODER_OAUTH2_PROVIDER_ENABLE=true +CODER_EXPERIMENTS=mcp-server-http ``` +For the YAML and Helm forms, refer to [Enable OAuth2 Provider](../admin/integrations/oauth2-provider.md#enable-oauth2-provider). + ### MCP Registry Coder is published to the official [MCP Registry](https://github.com/modelcontextprotocol/registry) @@ -183,7 +185,7 @@ server advertises its OAuth2 capabilities via the `WWW-Authenticate` header and This enables a seamless connect-and-authenticate experience where users sign in through their browser without manually managing tokens. > [!NOTE] -> OAuth2 requires the `oauth2` experiment to be enabled on your Coder deployment. +> OAuth2 requires `CODER_OAUTH2_PROVIDER_ENABLE=true` on your Coder deployment. ### Session Token (For Programmatic Access) @@ -235,6 +237,6 @@ them for you to invoke, for example as slash commands: ### OAuth2 authentication not working -- Ensure your Coder deployment has the `oauth2` experiment enabled +- Ensure your Coder deployment has `CODER_OAUTH2_PROVIDER_ENABLE=true` set - Verify your MCP client supports RFC 9728 Protected Resource Metadata - Check that your browser can reach the Coder authorization endpoint diff --git a/docs/install/releases/feature-stages.md b/docs/install/releases/feature-stages.md index f7faa466876..0b4ed74f209 100644 --- a/docs/install/releases/feature-stages.md +++ b/docs/install/releases/feature-stages.md @@ -97,9 +97,9 @@ available in the documentation. - **Production-ready**: Yes - **Support**: Yes, [based on license](https://coder.com/pricing). -All features that are not explicitly tagged as `Early access` or `Beta` are -considered generally available (GA). They have been tested, are stable, and are -enabled by default. +All features that are not explicitly tagged as `Early access` or `Beta` are considered generally available (GA). +They have been tested, are stable, and are enabled by default. +A few GA features are off by default and have a server setting to turn them on, such as the [OAuth2 provider](../../admin/integrations/oauth2-provider.md) with `CODER_OAUTH2_PROVIDER_ENABLE`. If your Coder license includes an SLA, please consult it for an outline of specific expectations. From e35b2e91f9b2cd467af078525a03b507ef6f2f24 Mon Sep 17 00:00:00 2001 From: Bobby Ho Date: Sat, 12 Sep 2026 11:11:45 -0700 Subject: [PATCH 2/2] docs: note the device authorization grant is not supported --- docs/admin/integrations/oauth2-provider.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/admin/integrations/oauth2-provider.md b/docs/admin/integrations/oauth2-provider.md index af594baa49c..a2ca88ed36d 100644 --- a/docs/admin/integrations/oauth2-provider.md +++ b/docs/admin/integrations/oauth2-provider.md @@ -662,6 +662,7 @@ The current implementation has these limitations: - A scope allowlist can only be declared at [Dynamic Client Registration](#dynamic-client-registration); applications created through the web UI or the management API cannot restrict which scopes a client may request - No client credentials grant support +- No device authorization grant support (RFC 8628) - Implicit grant (`response_type=token`) is not supported; OAuth 2.1 deprecated this flow due to token leakage risks, and a request for it redirects to the registered callback with `unsupported_response_type` - Limited to opaque access tokens (no JWT support)