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.