Skip to content

feat(cloud): experimental cloud access for scoped API keys - #1439

Open
balanza wants to merge 8 commits into
mainfrom
feature-access-request
Open

balanza wants to merge 8 commits into
mainfrom
feature-access-request

Conversation

@balanza

@balanza balanza commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #1131

Supersedes #1132

What

cloud access lets an agent get a short-lived, narrowly scoped API key that a person approves in the browser, so it doesn't have to reuse a long-lived key with broad permissions.

  • cloud access roles lists the roles the OAuth user can assign in the selected organization.
  • cloud access request [--perms role:<UUID>,…] files a request, waits for approval in the browser, and saves the issued key to .clickhouse/credentials.json.

Both commands are compiled only with the experimental-access-negotiation cargo feature. Published binaries don't include them; CI runs clippy and tests with the feature enabled.

cargo install --path crates/clickhousectl --features experimental-access-negotiation

How the request works

Authorization code flow with PKCE (RFC 7636) and a loopback redirect (RFC 8252):

  1. Bind 127.0.0.1 (or [::1]). File the request with the redirect URI, the S256 challenge, a CSRF state and an optional role proposal.
  2. Print the approval URL to stderr and open the browser.
  3. Wait for the redirect, which carries either the code or error=access_denied. The wait ends at the server's pending deadline or after --timeout-seconds, whichever comes first (default two minutes). The request status is never polled.
  4. Exchange the code, verifier and redirect URI for the key.

Identity is always the refreshed OAuth user login, never an API key, even when one would win normal precedence. The organization comes from the user's membership list: a single membership is selected automatically; otherwise use --org/--org-id or --org-name.

Reviewing

Each commit builds and passes tests on its own:

  1. test(cli): an unrelated test isolation fix.
  2. feat(api): library-only organization_assignable_roles_get_list and the AssignableRole* models. Bearer only; no fallback to the administrative catalog.
  3. refactor(cloud): CloudClient construction groundwork. No behaviour change.
  4. feat(cloud): the feature itself. src/cloud/access.rs is the core. The commit message walks through the flow and the safety properties: no redirects followed on the handshake, the code and verifier are scrubbed from server messages, a 30-second bound per HTTP operation, and no retries of filing or the exchange.

Notes

  • Docs live in docs/reference/authentication.md under an experimental heading, not in the README.
  • No status polling: denial arrives on the redirect, expiry comes from the filing response, and the token endpoint enforces single use. A denial that never reaches this browser waits until the deadline.
  • Two local Postgres tests fail or flake on this machine, and also on main: failed_fresh_start_preserves_postgres_identity_without_polluting_clickhouse_selection and file_and_stdin_stop_on_error_and_preserve_psql_error_status.

Note

Medium Risk
Adds OAuth-gated role discovery and a PKCE flow that writes API credentials locally; risk is mitigated by compiling the feature off in published binaries, but handshake and credential handling remain security-sensitive for opt-in builds.

Overview
Adds an experimental cloud access command group (feature experimental-access-negotiation, off in default/published builds) so agents can discover caller-assignable roles and obtain human-approved, scoped API keys via a browser PKCE handshake instead of reusing long-lived keys.

API library: New Bearer-only organization_assignable_roles_get_list and AssignableRole* models on the existing org roles route—distinct from the administrative organization_roles_get_list catalog—with validation and test coverage.

CLI: cloud access roles lists assignable roles for the OAuth user’s organization; cloud access request runs loopback redirect, PKCE filing/exchange, stores the issued key in credentials (secret never printed), with timeouts, org membership resolution, and extensive unit/integration tests. CloudClient gains OAuth-for-access paths and request_auth for unmodeled handshake endpoints.

CI/docs: Workflow runs clippy/tests with the feature; authentication reference documents build/install and flow details.

Reviewed by Cursor Bugbot for commit fa0a2ca. Bugbot is set up for automated code reviews on this repo. Configure here.

@balanza

balanza commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator Author

Blocked by #1288

@balanza
balanza marked this pull request as ready for review November 13, 2026 07:02

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@balanza
balanza force-pushed the feature-access-request branch from 26d168f to 2915150 Compare November 13, 2026 10:11
GET /v1/organizations/{organizationId}/roles answers differently by auth:
an API key gets the administrative catalog (RBACRole), a CLI user Bearer
token gets the roles that user may assign. Model the second as its own
method, organization_assignable_roles_get_list, with AssignableRole,
AssignableRolePolicy and AssignableRolePolicyTags.

The method refuses Basic clients locally with AuthMismatch instead of
falling back to the catalog. Fields stay Option, per the library's
compatibility policy, so callers can tell a missing policy list from an
empty one. The analyzer allowlists the extra typed helper for the
existing route.
…lane

Rename from_resolved to from_resolved_auth and pass the resolved auth
straight through. Normalize the saved OAuth API URL in for_oauth_tokens,
as every other construction path already does, so a record saved without
the /v1 suffix resolves the same base URL.

Extract print_client_diagnostics from the --debug block so a command that
builds its own client can report the same credential source and API URL.
`cloud access` lets an agent get a short-lived, narrowly scoped API key that
a human approves in the browser, instead of reusing a long-lived key. It is
compiled only with the new `experimental-access-negotiation` feature, so
published binaries carry none of it; CI runs clippy and tests with it on.

Identity: both subcommands refresh and use the OAuth user login
(`CloudClient::for_access`), never an API key, even when one outranks it.
The API URL is `--url`, else the one saved with the login. The organization
comes from the user's complete membership list: one is picked
automatically, otherwise `--org`/`--org-id` or `--org-name`. Selectors are
reparsed without clap's global propagation, which would otherwise hide a
conflict between values given at different command depths.

`cloud access roles` prints the assignable-role menu. Incomplete roles or
policies fail before any output instead of implying an empty permission
set.

`cloud access request` runs the authorization code flow with PKCE
(RFC 7636) over a loopback redirect (RFC 8252):

1. bind 127.0.0.1 (or [::1]) and file the request with the redirect URI,
   S256 challenge, CSRF state and an optional `--perms role:<UUID>`
   proposal;
2. print the approval URL to stderr and open the browser;
3. wait for the redirect, which carries the code or `error=access_denied`;
   the wait is bounded by the server's pending deadline and
   `--timeout-seconds` (default two minutes), and the request status is
   never read;
4. exchange code, verifier and redirect URI for the key, and save it to
   `.clickhouse/credentials.json`.

The handshake client never follows redirects, so the code and verifier
cannot be replayed to another origin. Server messages are bounded and
scrubbed of the code and verifier. Each HTTP operation is capped at 30
seconds. Filing and the exchange are not retried. JSON stdout contains only
the final result.

Docs live in the authentication reference, under an experimental heading,
rather than the README.
Serve dedicated approved and denied loopback pages styled like the
console's access-request confirmation view, with a 5-second countdown
that tries to close the tab.
@balanza
balanza force-pushed the feature-access-request branch from 2fd91f2 to 1b0fe5a Compare November 17, 2026 12:31

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 336fb52. Configure here.

@balanza
balanza force-pushed the feature-access-request branch from 336fb52 to 110b8a0 Compare November 17, 2026 14:47
@balanza

balanza commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Audit CI won't pass until we merge #1475

@cla-assistant

cla-assistant Bot commented Nov 18, 2026

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ balanza
❌ chloecdc
You have signed the CLA already but the status is still pending? Let us recheck it.

This branch was previously deployed

1 inactive (outdated) deployment
cloud-integration — 17f5e8d6 Deployed Nov 13, 2026 by balanza via Cloud integration tests #1983
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

run-cloud-integration Run live Cloud integration tests for this PR head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cloud access request negotiation: role discovery, OAuth org selection and approval flow

2 participants