mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
Bobby Ho
fbac602456
`POST /oauth2/register` (RFC 7591 Dynamic Client Registration) has exactly one gate today: `ExperimentOAuth2`, a static, process-lifetime flag that wraps the entire `/oauth2/*` route tree as an all-or-nothing switch. That flag is scheduled for removal at GA, which would leave DCR with zero admin control at all once it is gone. Add a persistent, DCR-specific `oauth2_dcr_enabled` deployment setting, independent of the experiment system, so admin control over DCR survives GA. `POST /oauth2/register` checks the flag and rejects new registrations with an RFC 7591-shaped `403` when disabled; discovery metadata (`GET /.well-known/oauth-authorization-server`) conditionally omits `registration_endpoint`. A new audited `GET`/`PUT /api/v2/oauth2-provider/settings` endpoint lets an owner toggle it live, no restart required. The setting defaults to disabled, matching the canonical design proposal; disabling only stops new self-registrations, clients that already registered continue to authorize and exchange tokens normally. Address issue described in [ENG-3056](https://linear.app/codercom/issue/ENG-3056/oauth2-dcr-admin-configurable-enabledisable). ## Where this sits in the request path ```mermaid sequenceDiagram autonumber participant A as Admin participant S as coderd participant DB as site_configs<br/>(oauth2_dcr_enabled) participant C as OAuth2/MCP Client Note over A,S: Admin toggles DCR (new) A->>S: PUT /api/v2/oauth2-provider/settings<br/>{dynamic_client_registration_enabled: false} S->>S: authorizeContext(ActionUpdate, ResourceDeploymentConfig) S->>DB: UPSERT oauth2_dcr_enabled = false S-->>A: 200 OK (audited) Note over C,S: Client discovery + registration afterward C->>S: GET /.well-known/oauth-authorization-server S->>DB: GetOAuth2DCREnabled (system ctx, every request, no cache) DB-->>S: false S-->>C: 200 metadata, registration_endpoint omitted C->>S: POST /oauth2/register S->>DB: GetOAuth2DCREnabled (system ctx, every request, no cache) DB-->>S: false S-->>C: 403 invalid_request,<br/>"Dynamic client registration is disabled" Note over C,S: A client that registered before the change is unaffected C->>S: GET /oauth2/authorize?client_id=... Note over S: no DCR-enabled check on this path S-->>C: 200 (proceeds normally) C->>S: PUT/DELETE /oauth2/clients/{client_id} (RFC 7592 self-management) Note over S: no DCR-enabled check on this path either S-->>C: 200 (proceeds normally) ``` ## Files changed: manual vs. generated Reviewers should focus on the **manual** files. The **generated** ones are `make gen` output that follows mechanically from the manual changes and don't need direct review. <details> <summary><b>Manual files (26)</b> — click to expand, grouped the same way as "Suggested review order" below</summary> **1. Database** | File | What changed | |---|---| | `coderd/database/queries/siteconfig.sql` | New `GetOAuth2DCREnabled`/`UpsertOAuth2DCREnabled` query pair on the existing generic `site_configs` table. No schema change. | | `coderd/database/dbauthz/dbauthz.go` | RBAC check (`rbac.ResourceDeploymentConfig`) on the two new query methods; extends the `subjectSystemOAuth2` system-actor role with read-only `ResourceDeploymentConfig` access, needed so the public discovery/registration endpoints can read the flag via `dbauthz.AsSystemOAuth2`. | | `coderd/database/dbauthz/dbauthz_test.go` | RBAC assertion coverage for `GetOAuth2DCREnabled`/`UpsertOAuth2DCREnabled` in the method-coverage test suite. | **2. Request gating (the actual feature)** | File | What changed | |---|---| | `coderd/oauth2provider/registration.go` | The actual gate: `CreateDynamicClientRegistration` reads the flag first and returns an RFC 7591-shaped `403` when disabled (defaults disabled if never configured). | | `coderd/oauth2provider/registration_test.go` | New unit test, `TestCreateDynamicClientRegistration_DCREnabled`: calls the handler directly (no HTTP server), covering enabled / explicitly disabled / never-configured. | | `coderd/oauth2provider/metadata.go` | `GetAuthorizationServerMetadata` conditionally omits `registration_endpoint` from discovery metadata when DCR is disabled. | | `coderd/oauth2provider/metadata_test.go` | New unit test, `TestGetAuthorizationServerMetadata_DCREnabled`: same three states, for the discovery handler. | **3. Admin settings endpoint** | File | What changed | |---|---| | `codersdk/oauth2.go` | New `OAuth2ProviderSettings` SDK type plus `Client.OAuth2ProviderSettings`/`PutOAuth2ProviderSettings` methods. | | `coderd/oauth2.go` | New `oauth2ProviderSettings`/`putOAuth2ProviderSettings` admin handlers (audited via `audit.InitRequest`); updates the `GetAuthorizationServerMetadata` call site to pass `api.Database`. | | `coderd/coderd.go` | Registers `GET`/`PUT /api/v2/oauth2-provider/settings`. | | `coderd/oauth2_provider_settings_test.go` | New test file: admin `GET`/`PUT` round-trip, default-disabled-before-any-`PUT`, and `403` for a non-owner on both `GET` and `PUT`. | **4. Audit wiring** | File | What changed | |---|---| | `coderd/database/types.go` | New `database.OAuth2ProviderSettings` audit-only struct (mirrors `NotificationsSettings`). | | `coderd/audit/diff.go` | Adds the new struct to the `Auditable` type union. | | `coderd/audit/request.go` | Adds the new struct to all four dispatch switches (`ResourceTarget`, `ResourceID`, `ResourceType`, `ResourceRequiresOrgID`). | | `codersdk/audit.go` | New API-facing `ResourceTypeOAuth2ProviderSettings` constant and its `FriendlyString` case. | | `enterprise/audit/table.go` | Field-level audit action map (`ActionTrack`/`ActionIgnore`) for the new struct. | | `coderd/database/migrations/000546_audit_oauth2_provider_settings.up.sql` | Adds `oauth2_provider_settings` to the `resource_type` Postgres enum, required for the audit wiring above (`resource_type` is a real enum, not a Go-only value). | | `coderd/database/migrations/000546_audit_oauth2_provider_settings.down.sql` | No-op (`ALTER TYPE ... ADD VALUE` can't be reverted). | **5. Test-suite ripple from the disabled-by-default flip** | File | What changed | |---|---| | `coderd/oauth2provider/oauth2providertest/helpers.go` | New shared test helper, `EnableDCR`, since DCR now defaults to disabled and many pre-existing tests need it turned on to register a client. | | `coderd/oauth2_test.go` | Adds `TestOAuth2DynamicClientRegistrationDisabled` (registers a client, disables DCR, verifies new registration is rejected while the existing client's self-management, authorize, and token exchange all keep working); calls `EnableDCR` in every pre-existing test that registers a client. | | `coderd/oauth2_error_compliance_test.go` | Calls `EnableDCR` in every test that registers a client, so RFC-error-format assertions aren't masked by the new disabled-by-default gate. | | `coderd/oauth2_metadata_validation_test.go` | Same: `EnableDCR` added to every registration-dependent test. | | `coderd/oauth2_security_test.go` | Same. | | `coderd/oauth2provider/validation_test.go` | Same (near-duplicate of `oauth2_metadata_validation_test.go` in a different package). | | `coderd/oauth2provider/provider_test.go` | Same. | | `coderd/mcp/mcp_e2e_test.go` | Same, for the MCP end-to-end dynamic-registration flow test. | </details> <details> <summary><b>Generated files (12)</b> — from <code>make gen</code>, no need to review directly</summary> `coderd/apidoc/docs.go`, `coderd/apidoc/swagger.json`, `coderd/database/dbmetrics/querymetrics.go`, `coderd/database/dbmock/dbmock.go`, `coderd/database/dump.sql`, `coderd/database/models.go`, `coderd/database/querier.go`, `coderd/database/queries.sql.go`, `docs/admin/security/audit-logs.md`, `docs/reference/api/enterprise.md`, `docs/reference/api/schemas.md`, `site/src/api/typesGenerated.ts`. </details> ## Suggested review order ### 1. Database Establishes the persisted setting and its RBAC rule; everything else builds on `GetOAuth2DCREnabled`/`UpsertOAuth2DCREnabled`. 1. `coderd/database/queries/siteconfig.sql` — the two new queries. Same boolean-encoding pattern as the existing `oauth2_github_default_eligible` key right above them in the same file. 2. `coderd/database/dbauthz/dbauthz.go` — the RBAC wrapper for those two queries, plus the `subjectSystemOAuth2` role extension (search this file for `ResourceDeploymentConfig`, it appears in both spots). 3. `coderd/database/dbauthz/dbauthz_test.go` — asserts the RBAC checks from (2) actually fire. ### 2. Request gating (the actual feature) Where `POST /oauth2/register` and discovery metadata change behavior. 1. `coderd/oauth2provider/registration.go` — the primary gate. Read this first; it's the feature. 2. `coderd/oauth2provider/registration_test.go` — its new unit test, exercising the gate's three states directly against the handler. 3. `coderd/oauth2provider/metadata.go` — the same gating pattern applied to the discovery `GET` endpoint. 4. `coderd/oauth2provider/metadata_test.go` — its new unit test. ### 3. Admin settings endpoint How an owner flips the setting live. 1. `codersdk/oauth2.go` — the `OAuth2ProviderSettings` SDK type and `Client` methods first; this is the public contract everything below implements against. 2. `coderd/oauth2.go` — the `GET`/`PUT` handlers themselves. 3. `coderd/coderd.go` — route registration, to see where those handlers get wired in. 4. `coderd/oauth2_provider_settings_test.go` — round-trip and permission tests. ### 4. Audit wiring Plumbing required so step 3's `PUT` is auditable; mechanical except for (3). 1. `coderd/database/types.go` — the audit-only struct; everything else in this layer exists to plumb it through. 2. `coderd/audit/diff.go` — adds it to the `Auditable` type union (the compiler enforces this one). 3. `coderd/audit/request.go` — the four dispatch switches; the one part of this layer worth reading closely. 4. `codersdk/audit.go` — the API-facing resource type constant. 5. `enterprise/audit/table.go` — the field-action map. 6. `coderd/database/migrations/000546_audit_oauth2_provider_settings.{up,down}.sql` — read last; a consequence of needing a new `resource_type` enum value for (1)-(5), not a design decision of its own. ### 5. Test-suite ripple from the disabled-by-default flip 1. `coderd/oauth2provider/oauth2providertest/helpers.go` — the new `EnableDCR` helper. Read first to understand the fix pattern before seeing it applied repeatedly. 2. `coderd/oauth2_test.go` — next, since it also contains the new `TestOAuth2DynamicClientRegistrationDisabled`, not just `EnableDCR` call sites. 3. The rest, in any order, they're mechanical repeats of the same one-line addition: `coderd/oauth2_error_compliance_test.go`, `coderd/oauth2_metadata_validation_test.go`, `coderd/oauth2_security_test.go`, `coderd/oauth2provider/validation_test.go`, `coderd/oauth2provider/provider_test.go`, `coderd/mcp/mcp_e2e_test.go`. ## Explicitly out of scope Per the design proposal: rate limiting on `POST /oauth2/register` (tracked separately), retroactively affecting already-registered clients when DCR is disabled (this only gates new self-registration), and an Initial Access Token requirement (a separate, follow-up ticket).
138 lines
6.0 KiB
Plaintext
138 lines
6.0 KiB
Plaintext
coder v0.0.0-devel
|
|
|
|
USAGE:
|
|
coder [global-flags] <subcommand>
|
|
|
|
Coder v0.0.0-devel — A tool for provisioning self-hosted development
|
|
environments with Terraform.
|
|
- Start a Coder server:
|
|
|
|
$ coder server
|
|
|
|
- Get started by creating a template from an example:
|
|
|
|
$ coder templates init
|
|
|
|
SUBCOMMANDS:
|
|
autoupdate Toggle auto-update policy for a workspace
|
|
completion Install or update shell completion scripts for the
|
|
detected or chosen shell.
|
|
config-ssh Add an SSH Host entry for your workspaces "ssh
|
|
workspace.coder"
|
|
create Create a workspace
|
|
delete Delete a workspace
|
|
dotfiles Personalize your workspace by applying a canonical
|
|
dotfiles repository
|
|
external-auth Manage external authentication
|
|
favorite Add a workspace to your favorites
|
|
list List workspaces
|
|
login Authenticate with Coder deployment
|
|
logout Unauthenticate your local session
|
|
logs View logs for a workspace
|
|
netcheck Print network debug information for DERP and STUN
|
|
notifications Manage Coder notifications
|
|
oauth2-provider Manage Coder OAuth2 provider settings
|
|
open Open a workspace
|
|
organizations Organization related commands
|
|
ping Ping a workspace
|
|
port-forward Forward ports from a workspace to the local machine. For
|
|
reverse port forwarding, use "coder ssh -R".
|
|
provisioner View and manage provisioner daemons and jobs
|
|
publickey Output your Coder public key used for Git operations
|
|
rename Rename a workspace
|
|
reset-password Directly connect to the database to reset a user's
|
|
password
|
|
restart Restart a workspace
|
|
schedule Schedule automated start and stop times for workspaces
|
|
secret Manage secrets
|
|
server Start a Coder server
|
|
show Display details of a workspace's resources and agents
|
|
speedtest Run upload and download tests from your machine to a
|
|
workspace
|
|
ssh Start a shell into a workspace or run a command
|
|
start Start a workspace
|
|
stat Show resource usage for the current workspace.
|
|
state Manually manage Terraform state to fix broken workspaces
|
|
stop Stop a workspace
|
|
support Commands for troubleshooting issues with a Coder
|
|
deployment.
|
|
task Manage tasks
|
|
templates Manage templates
|
|
tokens Manage personal access tokens
|
|
unfavorite Remove a workspace from your favorites
|
|
update Will update and start a given workspace if it is out of
|
|
date. If the workspace is already running, it will be
|
|
stopped first.
|
|
users Manage users
|
|
version Show coder version
|
|
whoami Fetch authenticated user info for Coder deployment
|
|
|
|
GLOBAL OPTIONS:
|
|
Global options are applied to all commands. They can be set using environment
|
|
variables or flags.
|
|
|
|
--client-tls-ca-file string, $CODER_CLIENT_TLS_CA_FILE
|
|
Path to a CA certificate file to trust for API and DERP connections.
|
|
|
|
--client-tls-cert-file string, $CODER_CLIENT_TLS_CERT_FILE
|
|
Path to a client certificate file for mTLS authentication with API and
|
|
DERP. Requires --client-tls-key-file.
|
|
|
|
--client-tls-key-file string, $CODER_CLIENT_TLS_KEY_FILE
|
|
Path to a client private key file for mTLS authentication with API and
|
|
DERP. Requires --client-tls-cert-file.
|
|
|
|
--debug-options bool
|
|
Print all options, how they're set, then exit.
|
|
|
|
--disable-direct-connections bool, $CODER_DISABLE_DIRECT_CONNECTIONS
|
|
Disable direct (P2P) connections to workspaces.
|
|
|
|
--disable-network-telemetry bool, $CODER_DISABLE_NETWORK_TELEMETRY
|
|
Disable network telemetry. Network telemetry is collected when
|
|
connecting to workspaces using the CLI, and is forwarded to the
|
|
server. If telemetry is also enabled on the server, it may be sent to
|
|
Coder. Network telemetry is used to measure network quality and detect
|
|
regressions.
|
|
|
|
--force-tty bool, $CODER_FORCE_TTY
|
|
Force the use of a TTY.
|
|
|
|
--global-config string, $CODER_CONFIG_DIR (default: ~/.config/coderv2)
|
|
Path to the global `coder` config directory.
|
|
|
|
--header string-array, $CODER_HEADER
|
|
Additional HTTP headers added to all requests. Provide as key=value.
|
|
Can be specified multiple times.
|
|
|
|
--header-command string, $CODER_HEADER_COMMAND
|
|
An external command that outputs additional HTTP headers added to all
|
|
requests. The command must output each header as `key=value` on its
|
|
own line.
|
|
|
|
--no-feature-warning bool, $CODER_NO_FEATURE_WARNING
|
|
Suppress warnings about unlicensed features.
|
|
|
|
--no-version-warning bool, $CODER_NO_VERSION_WARNING
|
|
Suppress warning when client and server versions do not match.
|
|
|
|
--token string, $CODER_SESSION_TOKEN
|
|
Specify an authentication token. For security reasons setting
|
|
CODER_SESSION_TOKEN is preferred.
|
|
|
|
--url url, $CODER_URL
|
|
URL to a deployment.
|
|
|
|
--use-keyring bool, $CODER_USE_KEYRING (default: true)
|
|
Store and retrieve session tokens using the operating system keyring.
|
|
This flag is ignored and file-based storage is used when
|
|
--global-config is set or keyring usage is not supported on the
|
|
current platform. Set to false to force file-based storage on
|
|
supported platforms.
|
|
|
|
-v, --verbose bool, $CODER_VERBOSE
|
|
Enable verbose output.
|
|
|
|
———
|
|
Report bugs and request features at https://github.com/coder/coder/issues/new
|