Browser login and callback protocol

Browser product login begins at the login endpoint, then UC returns to the product callback. Both use navigation, Cookies, and one-time server state rather than a regular PAT JSON sequence.

Start login

GET /auth/login. The deployment determines the actual product prefix.

Browser navigation example; return_to is the in-product path after login:

GET $PRODUCT_ENDPOINT/auth/login?return_to=%2Fworkspace%2Fexample&lang=zh-CN

Parameter

Location

Description

return_to

query

Optional in-product relative path, mutually exclusive with product_continuation. If both are omitted, the service uses /

product_continuation

query

Optional server-issued one-time handoff value, mutually exclusive with return_to. Callers cannot forge it

lang

query

Optional account-login UI language: zh-CN, en-US, fr-FR, es-ES, ar, id-ID; case-sensitive

Explicitly empty return_to/product_continuation, repeated target parameters, or both targets cause failure navigation. Repeated/unsupported lang directly returns 400/ErrParamInvalid. Relative targets are limited to 2048 bytes, start with one / rather than //, contain no backslash, and parse without Host/User/absolute-URI/opaque components. These rules do not replace complete production-domain/callback configuration validation.

Success returns 302, Location, and the login-binding Cookie. Continue the full flow at the UC authorization page;302 does not mean login completed. Browsers/callers must retain Cookies under the correct origin/path. See Cookies and environments.

The server creates state, nonce, PKCE verifier, and binding values. The UC authorization URL uses an S256 challenge and product continuation. Existing continuation consumption and subsequent login-state creation share one system transaction. After failure, callers must not reuse old handoff values themselves. With continuation, UI language comes from its issuing state; lang does not override it. TTL is deployment-configured, not inferred from test values.

Complete the login callback

GET /auth/callback. UC navigates to this address; business callers must not construct token-exchange requests themselves.

Parameter

Location

Current consumption

state

query

Server-issued state. The handler uses the first value, which must match the binding Cookie and an unconsumed record

code

query

Authorization code. Exactly one of code and error must be nonempty

error

query

Upstream failure identifier, mutually exclusive with nonempty code

Per-state binding Cookies take precedence. The old fixed binding Cookie is read only if the per-state Cookie is absent. Repeated Cookies, missing binding, or invalid state cause failure navigation. If state contains a UI-language suffix, the full value enters the stored hash; the Cookie-name token excludes the suffix.

The callback consumes state/associated continuation, exchanges and validates tokens, checks nonce and active UC session/subject, then persists product identity/session. One-time state consumption commits before UC exchange. The entire callback is not one atomic transaction spanning UC/local storage. Do not automatically replay the original callback after downstream failure.

Success sets product session and CSRF Cookies, clears this login-binding Cookie, and redirects302 to the original safe target. Inactive UC sessions or missing handles may restart login once and clear old session Cookies; another failure opens the failure page. Arbitrary302 does not prove a product session exists. Read the current session afterward.

Persistence retries only MySQL numeric code 20702, at most three attempts100 milliseconds apart using new transactions, stopping promptly on cancellation. This does not authorize browser replay. Provider/state/persistence errors generally cause failure navigation; failure constructing that navigation may return 500.

Last updated on