feat(cli): optionally store session token in OS keyring #20256

zedkipp · 2025-10-09T23:45:22Z

This change implements optional secure storage of the CLI token using the operating system keyring for Windows, with groundwork laid for macOS in a future change. Previously, the Coder CLI stored authentication tokens in plaintext configuration files, which posed a security risk because users' tokens are stored unencrypted and can be easily accessed by other processes or users with file system access.

The keyring is opt-in to preserve compatibility with applications (like the JetBrains Toolbox plugin, VS code plugin, etc). Users can opt into keyring use with a new --use-keyring flag.

The secure storage is platform dependent. Windows Credential Manager API is used on Windows. The session token continues to be stored in plain text on macOS and Linux. macOS is omitted for now while we figure out the best path forward for compatibility with apps like Coder Desktop.

https://www.notion.so/coderhq/CLI-Session-Token-in-OS-Keyring-293d579be592808b8b7fd235304e50d5

#19403

cli/login.go

dogfood/coder/Dockerfile

code-asher

Very cool addition.

Thought I would come by with a perspective of how this might affect the VS Code and JetBrains plugins (and left some other comments while I was here).

In VS Code, we manually write the session file, and expect the CLI to use it. @EhabY to double check me on this.

In JetBrains, we call the login command to create the session file, but I think we also sometimes try to read the session file directly or check that it exists. @fioan89 to double check me on this.

All this to say, should using the keyring be opt-in? We may break the plugins otherwise. The main scenario that comes to my mind is that there is an expired token in the keyring and the VS Code plugin is unable to log in.

cli/sessionstore/sessionstore.go

cli/sessionstore/sessionstore_test.go

cli/login.go

cli/root.go

EhabY · 2025-10-24T18:05:30Z

In VS Code, we manually write the session file, and expect the CLI to use it. @EhabY to double check me on this.

Yes, as part of the OAuth work, I'm thinking of ditching that approach since it's not really secure (writing the token in plaintext to some globally accessible file). The idea I have in mind is to use VS Code's secrets API to store the label -> session_token pairs and pass that to the CLI using an environment variable when executing a command.

zedkipp · 2025-10-24T21:48:48Z

Very cool addition.

Thought I would come by with a perspective of how this might affect the VS Code and JetBrains plugins (and left some other comments while I was here).

In VS Code, we manually write the session file, and expect the CLI to use it. @EhabY to double check me on this.

In JetBrains, we call the login command to create the session file, but I think we also sometimes try to read the session file directly or check that it exists. @fioan89 to double check me on this.

All this to say, should using the keyring be opt-in? We may break the plugins otherwise. The main scenario that comes to my mind is that there is an expired token in the keyring and the VS Code plugin is unable to log in.

Thanks for the input @code-asher! Your comments were helpful. After learning about how session tokens are used with Coder Desktop and VS Code/Jetbrains plugins I took this feature a different direction. Essentially keyring use is now opt-in, and there's a future path forward to share the session token across applications. I put more details in the notion link in the PR description.

code-asher

Awesome, I like how the flag also removes the ambiguity of whether the keyring will be used, very nice 👌

cli/sessionstore/sessionstore.go

cli/sessionstore/sessionstore_test.go

cli/sessionstore/sessionstore_windows_test.go

This change implements optional secure storage of the CLI token using the operating system keyring for Windows, with groundwork laid for macOS in a future change. Previously, the Coder CLI stored authentication tokens in plaintext configuration files, which posed a security risk because users' tokens are stored unencrypted and can be easily accessed by other processes or users with file system access. The secure storage is platform dependent. Windows Credential Manager API is used on Windows. The session token continues to be stored in plain text on macOS and Linux. macOS is omitted for now while we figure out the best path forward for compatibility with apps like Coder Desktop.

fioan89 · 2025-10-28T21:16:49Z

Hey everyone, sorry for the late feedback.

In JetBrains, we call the login command to create the session file, but I think we also sometimes try to read the session file directly or check that it exists. @fioan89 to double check me on this.

Coder Toolbox does only login, it no longer stores the token in plain text.

The session token continues to be stored in plain text on macOS and Linux.
If it's worth any salt, JetBrains Toolbox also needs to securely store secrets. On macOS they developed a Java wrapper over they secure Keychain framework. On Linux there there are two wrappers over KWallet and libsecret, not sure what is the fallback order (hard to debug through the toolbox bytecode) and there is also a custom keychain like implementation where secrets are stored using an encryption key. This is the fallback if all things fail.

Essentially keyring use is now opt-in

This means apps vs code coder extension and Code toolbox will have to make a deliberate choice whether or not they should use the secure keychain. Will there be a way for these two apps to query the cli and check if keyring is available 🤔 ?

cli/keyring_test.go

deansheather

I'm confused what the flow is like with the support for multiple logins on separate hosts. How does the agent know which host it's supposed to use?

Windows implementation seems sound though!

deansheather · 2025-10-30T14:15:09Z

cli/sessionstore/sessionstore.go

+
+// keyringProvider represents an operating system keyring. The expectation
+// is these methods operate on the user/login keyring.
+type keyringProvider interface {


Does the provider interface need to have the service exposed as a parameter on methods? I imagine it could just be passed to the provider when it's instantiated and then used for all Set/Get/Delete operations.

My thinking here is I think we're better off storing the service name one level up (where we call out to a keyringProvider), rather than prescribing each keyringProvider to implement a way to store the service name. This closely mirrors what most of the OS keyring API's look like.

zedkipp · 2025-10-30T16:05:51Z

I'm confused what the flow is like with the support for multiple logins on separate hosts. How does the agent know which host it's supposed to use?

There's no support for logins on separate hosts right now, but the JSON storage format in the keyring should allow that in the future. I think this is consistent with how the CLI works today (it stores one token in .coderv2/session for the URL in .coderv2/url), but allows future expansion if needed.

code-asher

Looks good!

One minor observation from using it: it would be nice if we errored earlier when there is no keyring with coder --use-keyring login, currently it lets me go as far as pasting a token, and then it finally fails.

code-asher · 2025-10-30T22:15:01Z

cli/sessionstore/sessionstore_windows.go

+const (
+	// defaultServiceName is the service name used in the Windows Credential Manager
+	// for storing Coder CLI session tokens.
+	defaultServiceName = "coder-v2-credentials"


Should this be set in sessionstore.go I wonder? Since probably we will want to share the default name with all the keyring provider implementations. Or would each implementation have a different default name?

Good question. I'm planning to cross this bridge when I add the macOS support shortly. If they can be the same, I'll move this to sessionstore.go at that time.

zedkipp · 2025-10-30T23:27:11Z

Looks good!

One minor observation from using it: it would be nice if we errored earlier when there is no keyring with coder --use-keyring login, currently it lets me go as far as pasting a token, and then it finally fails.

Good observation! I made a small change to fail fast in this scenario, and updated the corresponding test.

github-actions bot assigned zedkipp Oct 9, 2025

zedkipp commented Oct 9, 2025

View reviewed changes

cli/login.go Outdated Show resolved Hide resolved

zedkipp commented Oct 15, 2025

View reviewed changes

dogfood/coder/Dockerfile Show resolved Hide resolved

zedkipp force-pushed the zedkipp/keyring branch from 9e95011 to e401787 Compare October 16, 2025 23:00

code-asher reviewed Oct 20, 2025

View reviewed changes

zedkipp force-pushed the zedkipp/keyring branch from e401787 to cffe005 Compare October 24, 2025 16:37

zedkipp changed the title ~~feat(cli): store session token in OS keyring with file fallback~~ feat(cli): optionally store session token in OS keyring Oct 24, 2025

zedkipp force-pushed the zedkipp/keyring branch from cffe005 to 1e0ca87 Compare October 24, 2025 21:21

zedkipp marked this pull request as ready for review October 24, 2025 21:48

zedkipp requested review from bcpeinhardt, code-asher and deansheather October 24, 2025 21:49

code-asher reviewed Oct 24, 2025

View reviewed changes

cli/sessionstore/sessionstore.go Show resolved Hide resolved

cli/sessionstore/sessionstore_test.go Outdated Show resolved Hide resolved

cli/sessionstore/sessionstore_windows_test.go Outdated Show resolved Hide resolved

zedkipp force-pushed the zedkipp/keyring branch from 1e0ca87 to da8034f Compare October 27, 2025 22:54

fioan89 reviewed Oct 28, 2025

View reviewed changes

cli/keyring_test.go Show resolved Hide resolved

deansheather reviewed Oct 30, 2025

View reviewed changes

code-asher approved these changes Oct 30, 2025

View reviewed changes

fix: fail fast when keyring is not available

ca18b6f

zedkipp merged commit 139dab7 into main Oct 30, 2025
48 checks passed

zedkipp deleted the zedkipp/keyring branch October 30, 2025 23:41

github-actions bot locked and limited conversation to collaborators Oct 30, 2025

feat(cli): optionally store session token in OS keyring #20256

feat(cli): optionally store session token in OS keyring #20256

Uh oh!

Conversation

zedkipp commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

EhabY commented Oct 24, 2025

Uh oh!

zedkipp commented Oct 24, 2025

Uh oh!

code-asher left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fioan89 commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

deansheather left a comment

Choose a reason for hiding this comment

Uh oh!

deansheather Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

zedkipp Oct 30, 2025 • 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!

zedkipp commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

code-asher left a comment

Choose a reason for hiding this comment

Uh oh!

code-asher Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

zedkipp Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

zedkipp commented Oct 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

zedkipp commented Oct 9, 2025 •

edited

Loading

code-asher left a comment •

edited

Loading

fioan89 commented Oct 28, 2025 •

edited

Loading

zedkipp Oct 30, 2025 •

edited

Loading

zedkipp commented Oct 30, 2025 •

edited

Loading