Add OAuth 2.1 authentication support #693

EhabY · 2025-12-16T14:32:23Z

Implements OAuth 2.1 with PKCE as an alternative authentication method to session tokens. When connecting to a Coder deployment that supports OAuth, users can choose between OAuth and legacy token authentication.

Key changes:

OAuth Flow:

Add OAuthSessionManager to handle the complete OAuth lifecycle: dynamic client registration, PKCE authorization flow, token exchange, automatic refresh, and revocation
Add OAuthMetadataClient to discover and validate OAuth server metadata from the well-known endpoint, ensuring server meets OAuth 2.1 requirements
Handle OAuth callbacks via vscode:// URI handler with cross-window support for when callback arrives in a different VS Code window

Token Management:

Store OAuth tokens (access, refresh, expiry) per-deployment in secrets
Store dynamic client registrations per-deployment in secrets
Proactive token refresh when approaching expiry (via ~~response interceptor~~ timers)
Reactive token refresh on 401 responses with automatic request retry
Handle OAuth errors (invalid_grant, invalid_client) by prompting for re-authentication

Integration:

Add auth method selection prompt when server supports OAuth
Attach OAuth interceptors to CoderApi for automatic token refresh (+ detach when no longer using OAuth)
Clear OAuth state when user explicitly chooses token auth
DeploymentManager coordinates OAuth session state with deployment changes

Error Handling:

Typed OAuth error classes (InvalidGrantError, InvalidClientError, etc.)
Parse OAuth error responses from token endpoint
Show re-authentication modal for errors requiring user action

Closes #586

EhabY · 2025-12-19T13:49:50Z

#633 includes some open threads that I addressed here but unsure about whether to revert or refine so please check open threads out, mainly:

code-asher

I have not reviewed the test code yet but I tried it out and it looks good!

code-asher · 2026-01-06T18:22:25Z

src/oauth/types.ts

@@ -0,0 +1,163 @@
+// OAuth 2.1 Grant Types


Did we try to pull these types from coder/coder? Some of these look slightly different, which to me implies these types are wrong (or maybe coder/coder's types are wrong).

For example ClientRegistrationRequest has required redirect_uris while Coder's is optional. Also we have an application_type field that does not seem to exist in either coder/coder nor in RFC 7591 nor 7592? Where does that come from? There may be other mismatches.

coder/coder does lack all the string enum types though unfortunately, maybe we can look into adding those on the coder/coder side at some point.

src/core/secretsManager.ts

code-asher · 2026-01-06T18:40:59Z

src/core/secretsManager.ts

+		// Extract relevant fields before serializing
+		const state: SessionAuth = {
+			url: auth.url,
+			token: auth.token,
+			...(auth.oauth && { oauth: auth.oauth }),
+		};


Why do we do this? At first I thought maybe SessionAuth was a superset of what we store or a different type, but we are converting it to another SessionAuth and it seems to have no extra fields so could we not serialize it directly?

This is because I used to pass a super set before and realized that JSON.stringify would serialize extra fields and thus when reading this we get the superset which caused strange hidden issues (I think we should always constrict this to the exact type)

I suppose if we removed it now someone could change this to a superset later and forget they should constrict it.

But, if we are going that route we should probably do it for all the properties including nested ones rather than just spread auth.oauth right?

src/core/secretsManager.ts

src/oauth/metadataClient.ts

src/oauth/utils.ts

code-asher · 2026-01-06T20:37:11Z

src/uri/uriHandler.ts

+	if (!state) {
+		logger.warn("Received OAuth callback with no state parameter");
+		return;
+	}


If this happens should we emit so we can abort the auth? Not sure if this is a recoverable error. I suppose the user could try opening the auth page again, but if the state was missing presumably it will still be missing.

Similar to the comment above, but we could have multiple windows that potentially each login to a different (or the same) deployment so that's why I'm hesitant about this. Maybe we can show something in the UI though and the user can cancel the flow if they wish?

Oof and there is no way for us to tell which login this callback was for. Bummer.

My intuition is that initiating multiple logins at a time will probably be uncommon, so if we do get a bad state most likely it does refer to whatever login is currently ongoing, and so it might make sense to surface this.

But yeah it does feel really bad that if someone is logging into multiple things at a time and we show some error or warning when really everything is fine.

If there was a way we could only error if the URI was unhandled, so we knew all logins ignored it because of the mismatched state, that could do the trick, because then we could show an error like "got a callback but none of the active logins matched it". But not sure how we would figure that out.

I feel like we leave this for now with a warning and see how it goes.

src/oauth/sessionManager.ts

code-asher · 2026-01-06T20:50:54Z

src/oauth/sessionManager.ts

+		this.logger.info("Revoking refresh token");
+
+		const params: TokenRevocationRequest = {
+			token: tokenToRevoke,


I think we are not exposing this type in coder/coder either if we want to do that eventually.

Implements OAuth 2.1 with PKCE as an alternative authentication method to session tokens. When connecting to a Coder deployment that supports OAuth, users can choose between OAuth and legacy token authentication. Key changes: OAuth Flow: - Add OAuthSessionManager to handle the complete OAuth lifecycle: dynamic client registration, PKCE authorization flow, token exchange, automatic refresh, and revocation - Add OAuthMetadataClient to discover and validate OAuth server metadata from the well-known endpoint, ensuring server meets OAuth 2.1 requirements - Handle OAuth callbacks via vscode:// URI handler with cross-window support for when callback arrives in a different VS Code window Token Management: - Store OAuth tokens (access, refresh, expiry) per-deployment in secrets - Store dynamic client registrations per-deployment in secrets - Proactive token refresh when approaching expiry (via response interceptor) - Reactive token refresh on 401 responses with automatic request retry - Handle OAuth errors (invalid_grant, invalid_client) by prompting for re-authentication Integration: - Add auth method selection prompt when server supports OAuth - Attach OAuth interceptors to CoderApi for automatic token refresh - Clear OAuth state when user explicitly chooses token auth - DeploymentManager coordinates OAuth session state with deployment changes Error Handling: - Typed OAuth error classes (InvalidGrantError, InvalidClientError, etc.) - Parse OAuth error responses from token endpoint - Show re-authentication modal for errors requiring user action

- Fix tests after rebase - Add proper OAuth error handling with re-authentication prompts - Remove in-memory token storage, rely on SecretStorage - Attach/detach OAuth interceptor based on auth method - Replace refreshIfAlmostExpired with smarter timer-based refresh - Combine OAuth tokens with session auth storage

- Split OAuthAuthorizer (login flow) from OAuthSessionManager (token lifecycle) - Add axios interceptor for automatic token refresh on 401 - Add comprehensive tests for session manager and interceptor - Rename oauthInterceptor to axiosInterceptor for clarity

- Fix critical issues from self-review - Fix URI handler for OAuth callback across windows - Add more tests for edge cases - Fix rebase conflicts

code-asher

Looks good to me! I think we may want to consider an always-attached 401 interceptor, and I wonder if we should remove the clearing from getStoredTokens() to avoid accidentally deleting tokens due to races (we could just return undefined without clearing I think).

EhabY force-pushed the oauth-support branch from 16da8fd to 8b91605 Compare December 18, 2025 08:20

EhabY requested a review from code-asher December 19, 2025 13:48

EhabY force-pushed the oauth-support branch 3 times, most recently from 24ebec5 to aa0e6b0 Compare December 24, 2025 13:54

EhabY mentioned this pull request Dec 30, 2025

Implement OAuth client in VS Code #633

Closed

EhabY force-pushed the oauth-support branch from 7da13f2 to 1aa0086 Compare December 30, 2025 10:16

code-asher reviewed Jan 6, 2026

View reviewed changes

EhabY force-pushed the oauth-support branch from 4db5149 to 6697a7c Compare January 8, 2026 10:02

EhabY added 4 commits January 8, 2026 17:09

Fix OAuth flow issues and improve test coverage

e5c5c9a

- Fix critical issues from self-review - Fix URI handler for OAuth callback across windows - Add more tests for edge cases - Fix rebase conflicts

Handle review comments on new PR

f690169

EhabY force-pushed the oauth-support branch from e6f1acb to f690169 Compare January 8, 2026 14:11

code-asher approved these changes Jan 9, 2026

View reviewed changes

Add OAuth 2.1 authentication support #693

Are you sure you want to change the base?

Add OAuth 2.1 authentication support #693

Uh oh!

Conversation

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

Uh oh!

Uh oh!

EhabY commented Dec 19, 2025

Uh oh!

code-asher left a comment

Choose a reason for hiding this comment

Uh oh!

code-asher Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

code-asher Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

EhabY Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

code-asher Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

code-asher Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

EhabY Jan 8, 2026

Choose a reason for hiding this comment

Uh oh!

code-asher Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

code-asher Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

code-asher left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

EhabY commented Dec 16, 2025 •

edited

Loading

EhabY Jan 8, 2026 •

edited

Loading

code-asher Jan 9, 2026 •

edited

Loading

code-asher left a comment •

edited

Loading