Sign in to a site for an agent

Sign in to the site behind a browserSession Connection from the dashboard, so that an agent’s browser sandbox starts signed in as you, or, on a shared Connection, as the account you sign in with.

You sign in on the site itself, in a browser that runs in the cluster and that you drive through a live view. The dashboard shows you the page and sends your clicks and keystrokes. When you press Done, the sandbox stores the browser’s session for the Connection’s sites in privacy-api and stops.

Prerequisites

• Enterprise, with the browser class and its sign-in class installed: sandbox.enabled: true, sandbox.browserClass.enabled: true and sandbox.browserClass.enrolment.enabled: true (the default). See Browser sign-in class.

• A browser Connection in the workspace. Add connection, then Sign in with a browser, makes one from its sign-in page (the install needs connections.browserSession.encryption set). One made with kubectl must name signInURL or signedOutWhen.urlPrefixes. See Browser sessions.

• The right role in the workspace:

  Connection scope	Who can sign in	Whose session is stored
  perUser	Any member	Yours
  shared	Owners	The workspace’s, which every user’s agent browses as

• The live view is a WebSocket that management-api serves, at /api/v1/sandboxes/{workspace}/{connection}/{claim}/view. The chart’s Gateway route and Ingress send /api/v1/sandboxes/ there. Behind a proxy of your own, route that prefix to management-api’s Service (port 8080), or set dashboard.wsProxy.url.

• dashboard.baseUrl set to the URL you open the dashboard at, when it is set at all. The live view accepts only a page from that origin; with it unset, only a page on the same host name as the WebSocket.

Sign in

1. In the dashboard, open Connections. The Connection’s row says whether you are signed in.

2. Press Sign in on its row (if you already are, choose Sign in again from the row’s menu). On a shared Connection the button is disabled unless you are a workspace owner.

   The dialog says Starting the sign-in browser… while the sandbox pod starts. It says Preparing if a previous sign-in of yours to this Connection is being cleared first. A sign-in you already have running is resumed.

3. When the site’s sign-in page appears, sign in as you would in your own browser. Click a field before you type into it.

   To paste a password or one-time code, click the field and paste with Ctrl+V (or Cmd+V). A paste must be one line of at most 4,096 characters. Press Enter yourself to submit the form.

4. When the site shows you signed in, press Done.

The status line shows the page the sandbox browser is on and how long you have left. The sandbox pod has five minutes to start. You then have the sign-in time, 15 minutes by default (sandbox.browserClass.enrolment.maxDuration, 1m to 20m). A sign-in not finished by then ends without storing anything.

To stop without storing anything, press Cancel or close the dialog.

When the page loads without its styles

Most sites load their styles and scripts from other hosts, such as static.licdn.com for www.linkedin.com. The sandbox reaches only the Connection’s hosts, so without those the page renders unstyled and its buttons do nothing. The dialog lists each refused host as a chip under the live view.

1. Press Allow beside a host. With several refused hosts, Allow all allows every one. Where a host is a subdomain, you can choose its wildcard instead, such as *.licdn.com.
2. Wait until Reload page is enabled. It reads Applying… until the sandbox can reach the allowed hosts.
3. Press Reload page. Allowing never reloads the page, so you can allow several hosts before one reload.

Allowing adds the host to the Connection’s hosts, so it needs a workspace editor; for anyone else the buttons are disabled.

Verify

After Done, the dialog closes and the Connection’s row reads Signed in followed by how long ago you finished.

Sign out on the row deletes your session.

The next browser sandbox that binds the Connection loads the session. Its browser tools stop answering connection_not_enrolled.

Troubleshooting

What you see	Cause and fix
No signed-in session was found for this site yet. Finish signing in, then press Done.	The browser holds nothing for the Connection’s sites yet. Finish signing in, then press Done again.
Storing the sign-in failed. Press Done to try again.	The sandbox could not store the session in privacy-api. Press Done again.
only a workspace owner may sign in to a shared Connection	The Connection’s scope is shared. Ask a workspace owner.
the Connection names neither browserSession.signInURL nor signedOutWhen.urlPrefixes	Set one of them on the Connection.
the workspace has as many enrolments running as it may	The workspace has reached sandbox.browserClass.enrolment.maxPerWorkspace running sign-ins. Try again when one ends.
container sandbox exited with code 1 (Error): browser-bridge failed: …	The sign-in browser stopped. The text after browser-bridge failed: is its reason: opening the start URL failed after <n> attempt(s) means the sign-in page failed to load. The sandbox retries network failures for up to a minute and ends on the first attempt for any other (check the enrol-…-egress Deployment in the workspace namespace and the Connection’s hosts); -state-… messages mean the sign-in class’s arguments are wrong. The claim and its pod are deleted two minutes after a failure, so read the message from the dialog or the claim’s Ready condition.
container enrolment-token exited with code 1 (Error): session-fetch failed: …	The single-use grant could not be copied into the sign-in pod. The text is session-fetch’s error.
… it left no message of its own — see the pod’s logs	The container crashed without saying why. Run kubectl describe pod on the enrol- pod within two minutes of the failure to read its log tail.
The sign-in browser could not start in time	The sandbox pod did not start within five minutes, or its egress proxy never became available, so the pod was never created. Check the workspace namespace’s events for the enrol- pod and its -egress Deployment.
Someone else is signing in to this Connection	Another owner started a sign-in to the shared Connection. Only the person who starts a sign-in can see or finish it, owners included. Try again when it ends.
Another window is already showing this sign-in	One live view at a time. Close the other window, then press Reconnect.
Browser sign-in is not set up on this cluster	The claim failed EnrolmentNotConfigured: the operator has no grant signer (privacy-api is not told the operator’s JWKS URL), no egress-proxy image, or no dashboard viewer namespace and labels. The claim’s Ready condition message names which.
The pane reads Disconnected. and offers Reconnect	The WebSocket to /api/v1/sandboxes/ does not reach management-api, or it is refused because the page’s origin is not dashboard.baseUrl, or you signed out. Check the first two in Prerequisites.

Related pages

• Connection reference: browser sessions
• SandboxClaim reference: enrolment
• Browser sign-in class