Plan: Add OAuth2 client_secret_basic (HTTP Basic auth) support

Context / why

codex mcp add is failing during the OAuth2 token exchange with:

• invalid_request: Missing client_id parameter

Coder’s OAuth2 provider currently identifies the client (client_id) and authenticates it (client_secret) only via query/form parameters, but RFC 6749 §2.3.1 requires supporting HTTP Basic authentication for confidential clients. This is especially important because Dynamic Client Registration (RFC 7591) defaults token_endpoint_auth_method to client_secret_basic.

Evidence (what we verified)

• coderd/httpmw/oauth2.go: extractOAuth2ProviderAppBase checks client_id only in query + form body and returns Missing client_id parameter otherwise.
• coderd/oauth2provider/tokens.go: extractTokenRequest requires client_id and client_secret as form fields for authorization_code grant.
• coderd/oauth2provider/metadata.go: discovery metadata advertises only client_secret_post today.
• User-provided curl shows /oauth2/tokens correctly parses form bodies (returns unsupported_grant_type when only client_id is supplied), so the failure is specifically “client_id not found where Coder looks for it”.

Goals

• Support OAuth2 client authentication via HTTP Basic on /oauth2/tokens (and other OAuth2 endpoints that expect client auth).
• Keep existing client_secret_post behavior working.
• Make discovery metadata match reality: advertise both client_secret_basic and client_secret_post.
• Improve RFC compliance for error responses: invalid_client with HTTP 401 should include WWW-Authenticate.

Non-goals

• Adding new OAuth2 grant types.
• Changing client_id format (it remains the app UUID).
• Reworking public-client (token_endpoint_auth_method=none) behavior beyond what’s needed for Basic auth.

Implementation plan

1) Parse client_id from HTTP Basic in the OAuth2 app lookup middleware

File: coderd/httpmw/oauth2.go

Target: extractOAuth2ProviderAppBase

Change: when client_id is not present in URL param, query string, or form body, fall back to HTTP Basic username.

paramAppID := r.URL.Query().Get("client_id")
if paramAppID == "" {
	if r.ParseForm() == nil {
		paramAppID = r.Form.Get("client_id")
	}
}
if paramAppID == "" {
	// RFC 6749 §2.3.1: support HTTP Basic client authentication.
	if user, _, ok := r.BasicAuth(); ok && user != "" {
		paramAppID = user
	}
}
if paramAppID == "" {
	errWriter.writeMissingClientID(ctx, rw)
	return
}

2) Support client_secret_basic during token exchange

File: coderd/oauth2provider/tokens.go

Targets: extractTokenRequest, and its callsite in Tokens().

Change: after parsing the form, merge credentials from form + Basic auth:

• basicUser/basicPass := r.BasicAuth()
• formClientID := vals.Get("client_id"), formClientSecret := vals.Get("client_secret")
• If Basic auth is present:
  • Prefer Basic auth values.
  • If both Basic and form provide a value and they conflict, return invalid_request (defensive + avoids ambiguous auth).
• Validate required fields based on grant_type, but validate the merged client_id/client_secret instead of requiring they exist in the form.

user, pass, basicOK := r.BasicAuth()
clientID := vals.Get("client_id")
clientSecret := vals.Get("client_secret")

if basicOK {
	if clientID != "" && clientID != user {
		// invalid_request: conflicting client_id
	}
	if clientSecret != "" && clientSecret != pass {
		// invalid_request: conflicting client_secret
	}
	clientID = user
	clientSecret = pass
}

// Now do grant-type-specific required checks:
// - authorization_code: require code + clientID + clientSecret
// - refresh_token: keep existing behavior unless we decide to tighten it

3) Update discovery metadata to advertise Basic auth support

File: coderd/oauth2provider/metadata.go

Change:

• Today: TokenEndpointAuthMethodsSupported: [client_secret_post]
• After: TokenEndpointAuthMethodsSupported: [client_secret_basic, client_secret_post]

4) Add RFC-required WWW-Authenticate header for invalid_client

File: coderd/httpapi/httpapi.go

Target: WriteOAuth2Error

Change: When writing an OAuth2 error with status==401 and error==invalid_client, set:

rw.Header().Set("WWW-Authenticate", `Basic realm=\"coder\"`)

This aligns with RFC 6749 §5.2 (“MUST include WWW-Authenticate when using 401”).

5) Tests

Add/extend tests to prevent regressions:

1. Token endpoint accepts Basic auth

   • Create OAuth2 app + secret.
   • Complete authorization-code issuance (existing test patterns already do this).
   • Exchange code at /oauth2/tokens while:
     • Setting req.SetBasicAuth(clientID, clientSecret)
     • Omitting client_id + client_secret from the form body
   • Expect HTTP 200.

2. Invalid secret via Basic returns invalid_client and includes WWW-Authenticate

   • Same setup, but send wrong password.
   • Expect HTTP 401, OAuth2 error invalid_client, and WWW-Authenticate: Basic realm="coder".

3. Metadata advertises both auth methods

   • Update coderd/oauth2provider/metadata_test.go to assert
     TokenEndpointAuthMethodsSupported contains both client_secret_basic and client_secret_post.

Acceptance criteria

• codex mcp add ... succeeds end-to-end against a Coder instance with OAuth2 provider enabled.
• /oauth2/tokens works for both:
  • client_secret_post (existing behavior)
  • client_secret_basic (new behavior)
• .well-known/oauth-authorization-server includes token_endpoint_auth_methods_supported with client_secret_basic.
• invalid_client responses return 401 + a WWW-Authenticate header.