Skip to content
LabTether

Login and Authentication Issues

You cannot log into the LabTether console, your session expires immediately after login, or you are getting permission errors on actions you expect to have access to.

Can't log in

Wrong password. The simplest explanation. If you are sure the password is correct, check for leading/trailing whitespace from a password manager autofill. Try typing the password manually.

Setup wizard not completed. If this is a fresh LabTether installation and no admin account has been created yet, the login page will not work because there are no accounts to log into. Complete the initial setup wizard first.

Browser cache and cookies. Stale session cookies can interfere with login. Clear cookies for the hub domain and try again in a fresh browser tab. An incognito/private window is the fastest way to rule out browser-side state problems.

Hub auth endpoint health. If the login form submits but nothing happens (or you get a generic server error), the hub's auth service may be down. Check:

curl -s https://<hub-host>:8443/healthz

If the health endpoint is also failing, the problem is hub-level, not auth-specific.

2FA problems:

  • "Invalid or expired challenge": 2FA challenge tokens expire after 5 minutes. If you took too long entering the code, start the login process over from the password step.
  • TOTP code rejected: Check that your device clock is accurate. TOTP allows roughly 30 seconds of drift. Also make sure you are using the code for the correct account if you have multiple TOTP entries in your authenticator app.
  • Lost authenticator app: Use one of your 8 recovery codes to log in (format: xxxx-xxxx). Once logged in, disable 2FA in settings and re-enable it with your new device.

Tip: If the console shows "Session check unavailable" after page load, try the "Try Again" button before signing out. Current builds preserve existing session state and do not force a logout on transient /api/auth/me failures.

SSO/OIDC problems

If you are using SSO via OIDC and login fails or behaves unexpectedly:

Issuer URL. The OIDC issuer URL must be exactly right, including trailing slashes and protocol. The hub fetches the .well-known/openid-configuration from this URL during login. If it is wrong, login will fail with a generic error. Verify it:

curl -s https://<issuer-url>/.well-known/openid-configuration | head -20

Client ID and secret. Confirm the client ID and secret configured in LabTether match what the identity provider has on file. A mismatched secret will fail silently from the user's perspective -- they just see a redirect loop or a generic error.

Redirect URI. The identity provider must have LabTether's callback URL registered as an allowed redirect URI. This is typically https://<hub-host>:8443/api/auth/oidc/callback. If it is missing or wrong, the IdP will reject the redirect.

Scope configuration. LabTether requests specific OIDC scopes (typically openid, profile, email). If the IdP does not support a requested scope or the client is not authorized for it, the login will fail. Check the IdP's client configuration for allowed scopes.

Role mapping. After a successful OIDC login, LabTether maps IdP claims to internal roles. If a user can log in via SSO but has no permissions, the role mapping is probably misconfigured. Check which claim field LabTether is reading for role assignment and what value the IdP is sending.

Clock skew. JWT validation is sensitive to clock drift between the hub and the identity provider. If the hub's clock is off by more than the token's tolerance (usually a few minutes), tokens will be rejected. Sync the hub's clock with NTP.

Permission errors

You can log in but get 403 Forbidden or "insufficient permissions" on specific actions.

Insufficient role. LabTether uses role-based access control. If your role does not include the permission for the action you are trying to perform, you will get a 403. Common examples:

  • Viewer role trying to start a terminal session (requires operator or admin)
  • Operator role trying to change system settings (requires admin)

Check your current role under your user profile in the console. If you need elevated access, an admin must update your role assignment.

Scope mismatch. Even with the right role, permissions can be scoped to specific node groups. If you have operator access to Group A but try to start a session on a node in Group B, the request will be denied. Verify that the target node is within your permission scope.

Policy changes. If something that used to work now returns a 403, a policy change is the most likely explanation. Ask your admin whether access policies were recently updated. This is especially common with saved terminal sessions -- a session that was created under a permissive policy will fail to reattach if the policy was tightened since.