feat(proxy): add verification_uri_complete to CLI SSO device flow

[yassin-berriai]

Relevant issues

Resolves LIT-3693. Reported via Pylon #4797 (CLI SSO device flow verification_uri_complete request)

Linear ticket

LIT-3693

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Changes

The CLI SSO device flow makes a same-host client read a user_code out of its terminal and type it into the browser to finish login. For daemon and background contexts where no terminal is visible, the code is effectively unreadable and login stalls. RFC 8628 §3.3.1 anticipates this with verification_uri_complete; a URL that embeds the user_code so the user confirms rather than transcribes.

This adds an opt-in verification_uri_complete to POST /sso/cli/start. The value is the same /sso/key/generate?source=litellm-cli&key=<login_id> browser-start URL the CLI already opens, with an added user_code query param. The user_code is carried across the SSO redirect through the OAuth state, the same channel that already carries login_id (state format is now {PREFIX}:{login_id}[:{user_code}]). After SSO completes and the browser_complete_token is minted, the verify page pre-fills the user_code input with the carried value, HTML-escaped, and the instruction text switches to "Confirm the verification code below" instead of pointing at a terminal.

The behavior is gated behind a new general_settings flag allow_cli_sso_verification_uri_complete, default false. When off, /sso/cli/start does not return verification_uri_complete and /sso/key/generate ignores the user_code query param, so the default deployment keeps the existing manual flow byte-for-byte. The flag is intended for same-host clients, where the device that starts the flow and the browser run on the same machine, and operators opt in explicitly. The submitted code is still hashed and compare_digest-checked, browser_complete_token is still required, and poll_secret handling, TTL, and single-use semantics are unchanged. The user_code query param is validated against the canonical server-issued format before it enters the OAuth state. There is no auto-submit.

The litellm CLI client is intentionally left unchanged; it is interactive and shows the code in the terminal already.

Screenshots / Proof of Fix

Live proxy on localhost:4000 loaded from this worktree (verified import litellm resolves to the worktree before testing).

Default deployment, flag off - no verification_uri_complete (manual flow, unchanged):

$ curl -s -X POST http://localhost:4000/sso/cli/start | python3 -m json.tool
{
    "login_id": "cli-C9KbajezU3-Kv5zLHe_zkktYHgz0LHkd",
    "poll_secret": "v31zQRz9MjQyJ66QB1ZjlVnMiaEwhwaU2YNPnHPLZSA",
    "user_code": "A4KE-QECH",
    "expires_in": 600
}

Operator opted in, general_settings.allow_cli_sso_verification_uri_complete: true - verification_uri_complete present and round-tripping source/key/user_code through the browser SSO start route:

$ curl -s -X POST http://localhost:4000/sso/cli/start | python3 -m json.tool
{
    "login_id": "cli-4IIL3Xfm8NIr0etbiJm7TIb6HR_BPpOm",
    "poll_secret": "JN6KgHYpK4hVNrww5TWtnRsbukiJeXZOL7Zd8YMAxV4",
    "user_code": "3897-5KZN",
    "verification_uri_complete": "http://localhost:4000/sso/key/generate?source=litellm-cli&key=cli-4IIL3Xfm8NIr0etbiJm7TIb6HR_BPpOm&user_code=3897-5KZN",
    "expires_in": 600
}

The browser SSO round-trip that renders the pre-filled verify page needs a real IdP, so it cannot be reproduced with curl against a headless proxy. That behavior is locked down by unit tests asserting the exact rendered HTML (prefilled value, HTML-escaping of a WXYZ-2345"><script> payload, the conditional instruction text, and no value attribute when no prefill is carried), the auth_callback state-forwarding path, and that google_login only threads user_code into the state when the operator opt-in is on.

Type

🆕 New Feature

Changes

litellm/proxy/management_endpoints/ui_sso.py

• cli_sso_start returns verification_uri_complete only when the operator opt-in is enabled
• new _cli_sso_verification_uri_complete_enabled() reads the general_settings flag; _cli_sso_start_response_body() builds the typed response
• google_login accepts a user_code query param and threads it into the OAuth state only when enabled
• _is_valid_cli_sso_user_code guards the user_code format before it enters the state
• _get_cli_state appends user_code to the state only for the opt-in flow
• auth_callback recovers user_code from the state and forwards it
• cli_sso_callback / _complete_cli_sso_callback_session thread prefill_user_code to the renderer
• _render_cli_sso_verification_page pre-fills the input (HTML-escaped) and switches the instruction text when present

litellm/proxy/_types.py

• documents allow_cli_sso_verification_uri_complete on ConfigGeneralSettings

ui/litellm-dashboard/src/lib/http/schema.d.ts

• regenerated for the new query param and general setting

[yassin-berriai]

@greptileai

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds opt-in verification_uri_complete support to the CLI SSO device flow (RFC 8628 §3.3.1), enabling same-host daemon clients to complete login via a single URL click instead of manually transcribing a code from a terminal. The feature is gated behind general_settings.allow_cli_sso_verification_uri_complete (default false) to preserve the phishing-resistant manual flow for all existing deployments.

• The user_code is validated against the server-issued format (_is_valid_cli_sso_user_code) before it enters the OAuth state, preventing state bloat; on recovery in auth_callback the value is HTML-escaped via escape(..., quote=True), and the actual code-verification step still uses compare_digest against the stored hash, so pre-filling is cosmetic only.
• The verify-page now conditionally renders "Confirm the verification code below…" vs. the original terminal instruction depending on whether a pre-fill is present, addressing the UX concern raised in earlier review rounds.
• All new behaviour is covered by 10 new unit tests (flag toggling, round-trip state parsing, XSS escaping, callback threading) and the one modified assertion strengthens an existing test by asserting prefill_user_code=None for the non-prefill path.

Confidence Score: 5/5

Safe to merge. All new behaviour is behind an explicit operator opt-in, the manual flow is byte-for-byte unchanged, and the implementation correctly guards injection and phishing vectors.

The feature is entirely additive: the default deployment path is untouched, the opt-in paths validate inputs before they reach the OAuth state and HTML-escape them before rendering, and the security-critical code-verification step (hash comparison) is unchanged. Tests cover the flag toggle, state round-trips, XSS payloads, and the callback threading path. No logic errors or broken contracts were found in the changed files.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/management_endpoints/ui_sso.py	Core implementation: adds opt-in verification_uri_complete, user_code format guard, state encoding/decoding, and conditional verify-page pre-fill. All paths are properly gated, HTML-escaped, and backward-compatible.
litellm/proxy/_types.py	Adds allow_cli_sso_verification_uri_complete field to ConfigGeneralSettings with a clear description of the security trade-off; straightforward and well-documented.
tests/test_litellm/proxy/management_endpoints/test_ui_sso.py	Adds 10 new tests covering the opt-in flag, state round-trips, user_code validation, XSS escaping in the pre-fill, and the callback path; existing test updated only to add the new prefill_user_code=None assertion (no weakening).
ui/litellm-dashboard/src/lib/http/schema.d.ts	Auto-generated schema update adding allow_cli_sso_verification_uri_complete to ConfigGeneralSettings and user_code query param to the google_login operation; consistent with the Python-side changes.

_{Reviews (5): Last reviewed commit: "fix(proxy): gate CLI SSO verification_ur..." | Re-trigger Greptile}

[yassin-berriai]

@greptileai

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[yassin-berriai]

Addressed both P2 findings in cf9d54c. The user_code query param is now validated against the canonical server-issued format ([A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}) via _is_valid_cli_sso_user_code before it is threaded into the OAuth state, so a known login_id cannot bloat the size-limited state with an arbitrary value; a non-conforming code falls back to the manual flow with no prefill. The verify-page instruction is now conditional, reading "Confirm the verification code below to finish this login" when the code is pre-filled. Added regression tests for the validator, the state-level guard (including a 4 KB code), and both instruction variants.

@greptileai

[greptile-apps]

Both fixes look solid.

Validator (_is_valid_cli_sso_user_code): The regex is correctly anchored with fullmatch and derived directly from _CLI_SSO_USER_CODE_ALPHABET, so it's impossible for the regex to drift from the generator's alphabet. The 4 KB test case ("A" * 4096) confirms the guard doesn't let large values through before fullmatch has a chance to trivially reject them.

State-level guard in _get_cli_state: Correct — invalid or oversized codes silently fall back to the two-part state, so existing clients that don't pass a user_code get identical behavior.

Conditional instructions: The two instruction strings are clearly differentiated and the tests assert both variants explicitly.

Callback path: After split(":", 2), prefill_user_code in auth_callback is whatever the IdP returned in the state param. Technically that value isn't re-validated at callback time, but it doesn't need to be: escape(..., quote=True) prevents XSS regardless of content, and the server-side hash check on submission rejects any value that wasn't issued by the server. Defense-in-depth would be a _is_valid_cli_sso_user_code guard before forwarding to cli_sso_callback, but it's not a correctness issue given the escaping and hash check are both in place.

The coverage is comprehensive — validator, state guard, 4 KB code, both instruction variants, round-trip parse, and the full callback-to-render path. LGTM.

[veria-ai]

PR overview

This PR updates the proxy CLI SSO device flow to support verification_uri_complete, allowing the SSO verification page to be opened with a user code already included. The touched code is in the proxy management UI SSO endpoint handling OAuth state and verification page prefill behavior.

There is still one open issue in the CLI SSO flow: the verification page can prefill a user code from OAuth state even when the new opt-in setting is disabled. If a user is induced to open a crafted authorization URL, they could complete approval for an attacker-controlled polling session. One issue has already been addressed, but this remaining flow-control gap keeps the PR at elevated risk until the prefill behavior is gated correctly.

Open issues (1)

• High: CLI SSO prefill bypasses opt-in — litellm/proxy/management_endpoints/ui_sso.py:1998

Fixed/addressed: 1 · PR risk: 7/10

[yassin-berriai]

Addressed in the latest revision. The verification_uri_complete behavior is now gated behind a new general_settings flag allow_cli_sso_verification_uri_complete, default false, so it is off for every deployment unless an operator explicitly enables it for the same-host case. The hash + compare_digest check on the submitted code and the browser_complete_token requirement are unchanged, and the user_code query param is validated against the canonical server-issued format before it enters the OAuth state.

[yassin-berriai]

Rebased onto the latest litellm_internal_staging (picks up the new type-discipline gate script that the lint job calls). No functional change from the prior commit; the operator opt-in gate, the user_code format guard, and the conditional verify-page text are unchanged.

@greptileai

[veria-ai]

High: CLI SSO prefill bypasses opt-in

prefill_user_code is trusted from the OAuth state even when allow_cli_sso_verification_uri_complete is disabled. An attacker can start a CLI SSO flow, craft an IdP authorization URL whose state contains their login_id:user_code, and have the victim land on a prefilled verification page that authorizes the attacker's polling session.

Suggested change

	prefill_user_code = state_parts[2] if len(state_parts) > 2 else None
	prefill_user_code = None
	if (
	len(state_parts) > 2
	and _cli_sso_verification_uri_complete_enabled()
	and _is_valid_cli_sso_user_code(state_parts[2])
	):
	prefill_user_code = state_parts[2]