feat!: support PKCE in the oauth2 client's auth/exchange flow #21215

Emyrk · 2025-12-10T21:16:20Z

Breaking Change: Existing oauth apps might now use PKCE. If an unknown type was being used, and it does not support PKCE, it will break.

To fix, set the PKCE methods on the external auth to none

export CODER_EXTERNAL_AUTH_1_PKCE_METHODS=none

PKCE challenge used in primary coderd oauth2 flow.
Closes #21213

Implementation from: golang/oauth2@55cd552

What this does

This adds PKCE support when Coder is the OAuth client to an external IdP.

OIDC

PKCE support is automatically detected from the well-known configuration endpoint. If it is supported, Coder will use it.

coder/cli/server.go

Lines 189 to 195 in 53fc864

    
           var pkceSupport struct { 
        
           	CodeChallengeMethodsSupported []promoauth.Oauth2PKCEChallengeMethod `json:"code_challenge_methods_supported"` 
        
           } 
        
           err = oidcProvider.Claims(&pkceSupport) 
        
           if err != nil { 
        
           	return nil, xerrors.Errorf("pkce detect in claims: %w", err) 
        
           }

OAuth (github login & external auth).

Known Oauth types have defaults set based on manual testing. We need to manually test to expand coverage.

Github 🟢
GitLab 🟢
Gitea 🟢
Bitbucket ❌ (not tested)
JFrog ❌ (not tested)
Azure ❌ (not tested)
Slack ❌ (not tested)

We assume PKCE is supported by all unknown oauth IdP's. This can fixed in the configuration

Example to disable:

export CODER_EXTERNAL_AUTH_1_PKCE_METHODS=none

Manual tests

Tested to work on:

Github ✔️ uses PKCE
- Failed code looks like: {"message":"Failed exchanging Oauth code.","detail":"oauth2: \"bad_verification_code\" \"The code passed is incorrect or expired.\" \"https://docs.github.com/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors/#bad-verification-code\""}
Gitlab ✔️ uses PKCE
- Failed code looks like: {"message":"Failed exchanging Oauth code.","detail":"oauth2: \"invalid_grant\" \"The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.\""}
Gitea ✔️ uses PKCE
Failed code looks like: {"message":"Failed exchanging Oauth code.","detail":"oauth2: \"unauthorized_client\" \"failed PKCE code challenge\""}
Auth0 ✔️ uses PKCE
- Failed code looks like: {"message":"Failed exchanging Oauth code.","detail":"oauth2: \"invalid_grant\" \"Invalid authorization code\""}

Used in coder primary auth

cli/server.go

github-actions · 2025-12-12T16:06:59Z

Task created: https://dev.coder.com/tasks/mafredri/f702c3a6-2206-437c-ae5f-f81ebab3260e

mafredri · 2025-12-12T16:12:36Z

📚 Documentation Check

✅ Updates Needed

docs/admin/external-auth/index.md - Add documentation for the new CODER_EXTERNAL_AUTH_N_PKCE_METHODS environment variable configuration option. This should explain:
- What PKCE (Proof Key for Code Exchange) is and why it's used
- How to configure it (e.g., CODER_EXTERNAL_AUTH_0_PKCE_METHODS="S256 plain")
- When administrators should enable it (security best practices, OAuth provider requirements)
- Which OAuth providers typically require or support PKCE

📝 Reasoning

This PR adds PKCE support for external OAuth2 authentication, which is a user-facing feature that requires administrator configuration. Based on my analysis:

What Changed:

Added CodeChallengeMethodsSupported field to ExternalAuthConfig and ExternalAuthLinkProvider
Added new environment variable CODER_EXTERNAL_AUTH_N_PKCE_METHODS for configuring PKCE methods
OIDC providers now auto-detect PKCE support from discovery metadata
API schemas were auto-generated and updated in /docs/reference/api/

Why Documentation is Needed:

This is a new configuration option that administrators need to know about
PKCE affects OAuth2 security and some providers may require it
The environment variable follows the existing pattern but isn't documented in /docs/admin/external-auth/index.md
Administrators need guidance on when and how to configure this option

What's Already Done:

API reference docs (schemas and general) were auto-generated ✅
No other documentation changes were included in this PR

This comment was generated by an AI Agent through Coder Tasks

mafredri

Minor nits/suggestions, but code changes look good otherwise 👍🏻. I agree with doc check that it would be good to have some added admin documentation.

mafredri · 2025-12-12T16:04:19Z

coderd/coderdtest/oidctest/idp.go

 	// clientID to be used by coderd
 	clientID     string
 	clientSecret string
+	pkce         bool // TODO: Implement for refresh token flow as well


Nit: TODO(name):, or perhaps track via GH ticket.

mafredri · 2025-12-12T16:11:41Z

coderd/coderdtest/oidctest/idp.go

+			if f.pkce {
+				challenge, ok := f.codeToChallengeMap.Load(code)
+				if !ok {
+					httpError(rw, http.StatusBadRequest, xerrors.New("code challenge not found for code"))


Suggested change

httpError(rw, http.StatusBadRequest, xerrors.New("code challenge not found for code"))

httpError(rw, http.StatusBadRequest, xerrors.New("challenge not found for code"))

This read a bit clearer to me, but if the original is more correct, keep it. Should we mention pkce here to give a hint pkce: challenge ...?

mafredri · 2025-12-12T16:12:37Z

coderd/coderdtest/oidctest/idp.go

+				codeVerifier := values.Get("code_verifier")
+				expecter := oauth2.S256ChallengeFromVerifier(codeVerifier)
+				if challenge != expecter {
+					httpError(rw, http.StatusBadRequest, xerrors.New("invalid code verifier"))


Suggested change

httpError(rw, http.StatusBadRequest, xerrors.New("invalid code verifier"))

httpError(rw, http.StatusBadRequest, xerrors.New("pkce: invalid code verifier"))

?

mafredri · 2025-12-12T16:13:08Z

coderd/coderdtest/oidctest/idp.go

+					httpError(rw, http.StatusBadRequest, xerrors.New("code challenge not found for code"))
+					return
+				}
+				codeVerifier := values.Get("code_verifier")


Empty handling?

mafredri · 2025-12-12T16:14:05Z

coderd/externalauth/externalauth.go

 		DisplayName: "Bitbucket Server",
 		Scopes:      []string{"PUBLIC_REPOS", "REPO_READ", "REPO_WRITE"},
 		DisplayIcon: "/icon/bitbucket.svg",
+		// TODO: PKCE support? Test 'S256' as the string value


I get the gist, but these TODOs could be a bit clearer, if someone else needs to look at it in the future.

mafredri · 2025-12-12T16:22:21Z

coderd/coderd.go

 					r.Route("/github", func(r chi.Router) {
 						r.Use(
-							httpmw.ExtractOAuth2(options.GithubOAuth2Config, options.HTTPClient, options.DeploymentValues.HTTPCookies, nil),
+							// Github supports PKCE S256


Do we need to call this out, link to docs?

mafredri · 2025-12-12T16:23:00Z

coderd/coderd.go

 						r.Use(
-							httpmw.ExtractOAuth2(options.GithubOAuth2Config, options.HTTPClient, options.DeploymentValues.HTTPCookies, nil),
+							// Github supports PKCE S256
+							httpmw.ExtractOAuth2(options.GithubOAuth2Config, options.HTTPClient, options.DeploymentValues.HTTPCookies, nil, []promoauth.Oauth2PKCEChallengeMethod{promoauth.PKCEChallengeMethodSha256}),


Suggestion: PKCESupported() on GithubOAuth2Config?

mafredri · 2025-12-12T16:23:58Z

codersdk/client.go

 	// OAuth2StateCookie is the name of the cookie that stores the oauth2 state.
 	OAuth2StateCookie = "oauth_state"
+
+	OAuth2PKCEChallenge = "oauth_pkce_challenge"


Also, since this is storing the verifier, not the challenge. Is the terminology correct?

mafredri · 2025-12-12T16:24:43Z

codersdk/deployment.go

 	// DisplayIcon is a URL to an icon to display in the UI.
-	DisplayIcon string `json:"display_icon" yaml:"display_icon"`
+	DisplayIcon                   string   `json:"display_icon" yaml:"display_icon"`
+	CodeChallengeMethodsSupported []string `json:"code_challenge_methods_supported" yaml:"code_challenge_methods_supported"`


Suggestion: Not sure if these docs get generated or not, but could add a description?

mafredri · 2025-12-12T16:28:19Z

coderd/externalauth/externalauth_test.go

 	const providerID = "test-idp"
 	fake := oidctest.NewFakeIDP(t,
-		append([]oidctest.FakeIDPOpt{}, settings.FakeIDPOpts...)...,
+		append([]oidctest.FakeIDPOpt{oidctest.WithPKCE()}, settings.FakeIDPOpts...)...,


Does this make it impossible to disable PKCE for tests when using setupOauth2Test?

mafredri · 2025-12-12T16:39:21Z

coderd/coderdtest/oidctest/idp.go

 			}
+
+			if f.pkce {
+				challenge, ok := f.codeToChallengeMap.Load(code)


We should also clean up this map after use.

feat: oauth2 client to use pkce in auth/exchange flow

08f52e9

Used in coder primary auth

github-actions bot assigned Emyrk Dec 10, 2025

Emyrk added 5 commits December 10, 2025 15:41

force pkce

40283ea

chore: pkce defaults

5eb6e9f

frontend test

53fc864

chore: sane defaults and make gen

ead92c8

make some tests use pkce

0be0bb2

Emyrk commented Dec 11, 2025

View reviewed changes

cli/server.go Show resolved Hide resolved

fmt

303ea30

Emyrk marked this pull request as ready for review December 11, 2025 16:28

Emyrk changed the title ~~feat: oauth2 client to use pkce in auth/exchange flow~~ feat: oauth2 client support for pkce in auth/exchange flow Dec 11, 2025

Emyrk changed the title ~~feat: oauth2 client support for pkce in auth/exchange flow~~ feat: support PKCE in the oauth2 client's auth/exchange flow Dec 11, 2025

fix tests

7af6c3a

Emyrk changed the title ~~feat: support PKCE in the oauth2 client's auth/exchange flow~~ feat!: support PKCE in the oauth2 client's auth/exchange flow Dec 11, 2025

Emyrk added the release/breaking This label is applied to PRs to detect breaking changes as part of the release process label Dec 11, 2025

Emyrk added 3 commits December 11, 2025 17:25

make gen

7f11ab7

fix tests

65b08c8

fix tests

c6b3b24

mafredri added the doc-check Assign this label to PRs to check for any doc changes. label Dec 12, 2025

mafredri self-requested a review December 12, 2025 16:06

mafredri reviewed Dec 12, 2025

View reviewed changes

	var pkceSupport struct {
	CodeChallengeMethodsSupported []promoauth.Oauth2PKCEChallengeMethod `json:"code_challenge_methods_supported"`
	}
	err = oidcProvider.Claims(&pkceSupport)
	if err != nil {
	return nil, xerrors.Errorf("pkce detect in claims: %w", err)
	}

	httpError(rw, http.StatusBadRequest, xerrors.New("code challenge not found for code"))
	httpError(rw, http.StatusBadRequest, xerrors.New("challenge not found for code"))

feat!: support PKCE in the oauth2 client's auth/exchange flow #21215

Are you sure you want to change the base?

feat!: support PKCE in the oauth2 client's auth/exchange flow #21215

Uh oh!

Conversation

Emyrk commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this does

OIDC

OAuth (github login & external auth).

Uh oh!

Uh oh!

github-actions bot commented Dec 12, 2025

Uh oh!

mafredri commented Dec 12, 2025

📚 Documentation Check

✅ Updates Needed

📝 Reasoning

Uh oh!

mafredri left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Emyrk commented Dec 10, 2025 •

edited

Loading