Skip to content

feat: allow coding agents to authenticate with claimable temporary accounts - #23225

Merged
dschaller merged 23 commits into
masterfrom
dschaller/agent-tmp-authn
May 22, 2026
Merged

dschaller merged 23 commits into
masterfrom
dschaller/agent-tmp-authn

Conversation

@dschaller

@dschaller dschaller commented May 18, 2026 •

Copy link
Copy Markdown
Member

Summary

Allow coding agents to authenticate with claimable temporary accounts

The CLI now detects common coding-agent environments and keeps normal human CLI authentication behavior unchanged. When running as an agent, it prefers existing usable credentials, but if home credentials are inaccessible it creates an ephemeral Pulumi account through the agent signup endpoint.

Automatically created agent credentials and claim metadata are stored in a shared temporary Pulumi directory (/tmp/.pulumi on non-Windows, <OS temp dir>/.pulumi on Windows) so sandboxed agent sessions on the same host and OS user can reuse them. The CLI prints claim instructions while claim metadata is present, asks agents to surface the claim URL, warns that claiming locks the org during the claim process, and tells agents to finish work before the user claims the account.

If agent authentication fails after the account has been claimed or otherwise becomes unavailable, the CLI asks the user to run pulumi login. It also explains that the stacks the agent was working with may have moved to the user’s Pulumi account and that the agent’s access to those stacks may have changed. The CLI validates stored claim tokens before surfacing stale claim URLs and records unavailable claims to avoid repeatedly checking them.

Expired claim state is cleaned up when the claim URL and access token have expired.

Test plan

  • Added appropriate unit tests - For all changes
  • Added a test in pkg/engine/lifecycletest - For all engine/protocol changes
  • Added a conformance test in pkg/testing/pulumi-test-language - For language protocol changes
  • Added a golden test in pkg/backend/display - For changes to the output renderers

Validation

  • make lint — clean
  • make test_fast — all pass
  • make tidy_fix — clean
  • make format — clean
  • Relevant SDK tests pass (if SDK changes)
  • make check_proto — clean (if proto changes)

Changelog

  • Changelog entry added. If you do not believe this PR requires a changelog, ask a maintainer to apply the impact/no-changelog-required label.

Risk

The main risk is unintended account selection in agent mode.

If the CLI misclassifies a human shell as an agent, it could enter the agent-auth fallback path. The current detection is env-var based, so this mainly happens if someone has agent-like env vars set outside an actual agent session.

Credential-source mistakes are the second risk. We explicitly avoided copying PULUMI_ACCESS_TOKEN or readable home credentials into /tmp, but bugs in this routing could leak user credentials into a shared temp dir. The current implementation only writes auto-created agent account credentials to the shared temporary Pulumi directory.

Another risk is orphaned infrastructure state. If signup succeeds and claim metadata is missing, expired, or never shown, an agent can create stacks in an account the user may not claim. The CLI now validates stored claim tokens before surfacing claim URLs after authentication failures, but claim instructions still depend on local claim metadata being written and preserved.

There is also a service compatibility risk: the CLI now depends on unauthenticated Pulumi Cloud agent signup and claim-validation endpoints. If those endpoint shapes change, agent auto-auth or stale-claim detection can break.

Blast Radius

Mostly CLI authentication behavior for detected coding-agent environments.

Non-agent human CLI behavior should be unchanged. Existing PULUMI_ACCESS_TOKEN, PULUMI_HOME, and PULUMI_CREDENTIALS_PATH behavior remains authoritative and should fail rather than silently falling back when those explicit paths are inaccessible.

For agents, the blast radius includes login/current-backend selection, stack listing, stack creation, service secrets access, private Pulumi Cloud template retrieval, and any command that needs a cloud backend. It can also affect shared host behavior because the shared temporary Pulumi directory is intentionally reused across sandboxed agents on the same machine, scoped by OS user permissions.

Public API

Yes, indirectly.

The CLI calls unauthenticated Pulumi Cloud agent endpoints:

  • GET /api/agents/signup
  • POST /api/agents/signup
  • GET /api/agents/signup/validate/{claimToken}

Signup is challenge-based. The first request receives challengeID and challengeData; the second request sends challengeID, challengeResult, and agent metadata.

The CLI relies on the final signup response contract:

{
"accessToken": "...",
"accessTokenValidUntil": "...",
"claimToken": "...",
"claimTokenValidUntil": "..."
}

The CLI derives the claim URL from claimToken.

If expiration timestamps are missing or malformed, the CLI cannot reliably decide when to stop showing claim warnings or when to clean up shared agent state.

@dschaller dschaller changed the title feat: allow coding agents to authenticate with claimable temporary ac… feat: allow coding agents to authenticate with claimable temporary accounts May 18, 2026
@dschaller
dschaller force-pushed the dschaller/agent-tmp-authn branch from 1abdf89 to ce6dcb2 Compare May 18, 2026 06:14
@tgummerer

Copy link
Copy Markdown
Collaborator

Is there a doc that explains a bit more how this is supposed to work, or can you explain it a bit more in the PR? E.g. how does the agent get associated with a user? Why is this agent specific, and a user can't create a claimable temporary account for themselves? Is the agent allowed to do anything until the account is claimed?

@dschaller
dschaller marked this pull request as ready for review May 21, 2026 21:15
@dschaller
dschaller requested a review from a team as a code owner May 21, 2026 21:15
@dschaller
dschaller requested a review from tgummerer May 21, 2026 21:15
Comment thread pkg/backend/httpstate/backend.go Outdated
Comment on lines +82 to +85
var agentCredentialUse = struct {
sync.Mutex
cloudURLs map[string]bool
}{

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plz don't make global vars

Comment thread pkg/cmd/pulumi/metadata/metadata.go Outdated
}

return ""
return agentdetect.Detect(getEnv)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's little value in a method that just forwards to another method, you can just delete this method and inline the use of agentdetect.Detect

@tgummerer tgummerer left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR is much too large for me to give it a review with any reasonable confidence.

A couple of user experience things stood out to me though.

  1. the agent credentials are created in /tmp, so if that is cleared out I think the user has no way of getting their current work back, leaving their cloud infrastructure orphaned, and the user puzzled what to do next, which seems bad.
  2. what happens if the user logs in without claiming the agent account? It'll also get orphaned right? Next time the agent will just use the users credentials, and forget all about the /tmp directory. I think if we have the agent credentials in PULUMI_HOME instead, we can give appropriate warnings to the user etc.

Doing that will also remove a whole bunch of "if agent then use this completely different directory" logic, making the rest of the code a bit easier to review.

changes:
- type: feat
scope: cli
description: Allow coding agents to authenticate with existing credentials when available and create claimable temporary accounts when home credentials are inaccessible

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
description: Allow coding agents to authenticate with existing credentials when available and create claimable temporary accounts when home credentials are inaccessible
description: Allow coding agents to create claimable temporary accounts when not authenticated

Comment on lines +308 to +323
if resp.AccessToken == "" {
return AgentSignupResponse{}, errors.New(
"creating agent Pulumi account: signup response did not include an access token")
}
if resp.AccessTokenValidUntil.IsZero() {
return AgentSignupResponse{}, errors.New(
"creating agent Pulumi account: signup response did not include accessTokenValidUntil")
}
if resp.ClaimToken == "" {
return AgentSignupResponse{}, errors.New(
"creating agent Pulumi account: signup response did not include a claim token")
}
if resp.ClaimTokenValidUntil.IsZero() {
return AgentSignupResponse{}, errors.New(
"creating agent Pulumi account: signup response did not include claimTokenValidUntil")
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feels weird. Shouldn't we be able to trust the services response when it didn't return an error?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this is somewhat being conservative in case the service returns the fields but they are empty

if runtime.GOOS == "windows" {
return filepath.Join(os.TempDir(), BookkeepingDir)
}
return filepath.Join("/tmp", BookkeepingDir)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why would we use /tmp for this, and are not reusing PULUMI_HOME? I thought these credentials were supposed to be valid for a few days? /tmp will get cleared out everytime someone reboots, so if someone reboots, and I understand the feature correctly they loose all the work they've done up until that point, without any possibility of reclaiming it, because they lost all the login data?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few reasons - PULUMI_HOME might not be set or might not be accessible by the agent for RW. /tmp is always going to be shared across all agent sessions and will be guaranteed to have RW permissions. We do give preference to the env var or existing known home paths over /tmp if the agent can access them

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh so we're creating new agent accounts even if there are potentially valid credentials somewhere? That feels like it's gonna be very confusing for users if they run the agent somewhere, it does a bunch of stuff with their infrastructure, and then we ask them to "claim" the org, even though they are logged in somewhere else already? I thought this was only a feature for new users, where the agent probably/hopefully has access to everything the user knows.

@dschaller dschaller May 22, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah if the agent is in a sandbox and can't see the valid creds on the host then we create a new account. We do show them the claim URL upfront so the idea is if they have a valid pulumi account they can configure the agent properly or let the agent run outside it's sandbox. The user can claim the account afterward if they have an existing pulumi account so it's also not like the resources are stuck there.

My understanding is this is for any user - even those who potentially have an existing account but do not have their agent configured to access their credentials or account. (At least the claim process supports it) cc @arunkumar611 for weighing in.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/tmp is always going to be shared across all agent sessions and will be guaranteed to have RW permissions.

Also I'm not sure I understand why this is true? It probably always has RW permissions, but if someone locks their agents down in a VM or whatever, they are not gonna have a shared /tmp here either way.

But again if agents are running in an environment where they can't access the regular pulumi credentials, this is gonna be a very confusing feature for users imo.

Comment on lines +408 to +409
"Tell them claiming the account will lock the Pulumi organization during the claim process, "+
"so they should let the agent finish its work before claiming it.\n",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The agent already can't really do anything here at this point right? So this may not be necessary.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The user can still claim the account even after the agent access token has expired

@iwahbe

iwahbe commented May 22, 2026

Copy link
Copy Markdown
Member

claiming locks the org during the claim process

What does it mean to lock an org here?

@tgummerer tgummerer mentioned this pull request May 22, 2026

@tgummerer tgummerer left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving this to get it in as we want to ship it soon, but I can't personally claim to have fully read and understood the code, and I think there's gonna be quite a bit of confusion for users with how this is currently implemented.

@dschaller

Copy link
Copy Markdown
Member Author

What does it mean to lock an org here?

We lock the source org (the ephemeral agent org) during the transfer process so changes can't happen from underneath us during the migration to the claiming users org

@tgummerer
tgummerer enabled auto-merge May 22, 2026 16:16
@tgummerer

Copy link
Copy Markdown
Collaborator

We lock the source org (the ephemeral agent org) during the transfer process so changes can't happen from underneath us during the migration to the claiming users org

FWIW, I'd describe that as something like "once the transfer process begins, no more changes are allowed until it completes", rather than with locking, which is likely easier to understand for end users. That can come in a follow up PR.

@tgummerer
tgummerer added this pull request to the merge queue May 22, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks May 22, 2026
@i-am-tom
i-am-tom enabled auto-merge May 22, 2026 18:05
@i-am-tom
i-am-tom added this pull request to the merge queue May 22, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks May 22, 2026
@dschaller
dschaller added this pull request to the merge queue May 22, 2026
Merged via the queue into master with commit adffab4 May 22, 2026
121 checks passed
@dschaller
dschaller deleted the dschaller/agent-tmp-authn branch May 22, 2026 20:21
jkeiser added a commit that referenced this pull request Jun 11, 2026
The CLI's four credential-grant write sites — agent signup, OIDC token
exchange, and the two refresh-token callbacks — each inlined the same
dance: write AccessToken, conditionally rotate RefreshToken, allocate
TokenInformation if nil, write the new ExpiresAt. The pairing of
AccessToken and ExpiresAt was code-review discipline, not a structural
guarantee, and broke at validateStoredAccount: its hourly /api/user
fetch overwrote the entire local TokenInformation with the response
struct, and /api/user never includes ExpiresAt. Any locally cached
expiry was clobbered seconds later.

For the new refresh-token callbacks, the freshly-written expiry was
being lost moments after the refresh. The same overwrite has silently
dropped signup/OIDC ExpiresAt on the first revalidation since
agent-signup shipped in #23225, but no read path there depended on it
surviving so the loss was invisible.

Centralize the credential-grant writes through a new
Account.SetCredentials(accessToken, accessTokenExpiresAt, refreshToken)
method. Change validateStoredAccount to copy only the Name /
Organization / Team fields /api/user actually reports, leaving the
cached ExpiresAt alone. The WithRefresh callback and internal
refresh/writeback signatures pick up the (accessToken,
accessTokenExpiresAt, refreshToken) order so the access token travels
with its own expiration across the wrapper boundary, leaving a natural
slot for a future refresh-token expiration next to the refresh token.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
jkeiser added a commit that referenced this pull request Jun 12, 2026
The CLI's four credential-grant write sites — agent signup, OIDC token
exchange, and the two refresh-token callbacks — each inlined the same
dance: write AccessToken, conditionally rotate RefreshToken, allocate
TokenInformation if nil, write the new ExpiresAt. The pairing of
AccessToken and ExpiresAt was code-review discipline, not a structural
guarantee, and broke at validateStoredAccount: its hourly /api/user
fetch overwrote the entire local TokenInformation with the response
struct, and /api/user never includes ExpiresAt. Any locally cached
expiry was clobbered seconds later.

For the new refresh-token callbacks, the freshly-written expiry was
being lost moments after the refresh. The same overwrite has silently
dropped signup/OIDC ExpiresAt on the first revalidation since
agent-signup shipped in #23225, but no read path there depended on it
surviving so the loss was invisible.

Centralize the credential-grant writes through a new
Account.SetCredentials(accessToken, accessTokenExpiresAt, refreshToken)
method. Change validateStoredAccount to copy only the Name /
Organization / Team fields /api/user actually reports, leaving the
cached ExpiresAt alone. The WithRefresh callback and internal
refresh/writeback signatures pick up the (accessToken,
accessTokenExpiresAt, refreshToken) order so the access token travels
with its own expiration across the wrapper boundary, leaving a natural
slot for a future refresh-token expiration next to the refresh token.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants