Skip to main content

Login Issues

Forgotten password​

OpSee delegates authentication entirely to Keycloak. Password resets must go through Keycloak:

  • If the "Forgot password" link is displayed on the login page, click it and follow the email reset flow. This requires a mail server to be configured in Keycloak.
  • If no reset link appears, a Keycloak administrator must manually reset your password: Keycloak Admin Console → Users → select your account → Credentials → Reset Password.

Session expired​

OAuth2 tokens have a limited lifetime. When your session expires, API requests return 401 and the UI may redirect you to the login page without warning.

Fix: Log out explicitly using the avatar menu (top right), then log back in. Closing and reopening the browser tab without logging out first can also resolve a stale session.

401 on every page after logging in​

If you are redirected to the login page, successfully authenticate, and then immediately see 401 errors again, the token stored in your browser may be corrupted.

Fix:

  1. Open browser developer tools → Application → Cookies: delete all cookies for the OpSee domain.
  2. Open Local Storage: delete all entries for the OpSee domain.
  3. Close the tab, reopen it, and log in again.

403 after login (can log in but cannot access anything)​

A 403 immediately after a successful Keycloak login means the account exists and authenticated correctly, but holds no grants in OpSee. Authentication and authorization are separate layers: a valid login proves who you are and grants nothing by itself.

Fix: an administrator assigns grants in Administration → Access Control → Users:

  1. Open the user record.
  2. Assign a business role (role:Operator, role:Supervisor, role:Technician, role:Quality, role:Planner, role:Viewer or role:Admin).
  3. Assign an equipment scope — a site or line role, or All equipment.
  4. Ask the user to sign out and back in; permissions are carried in a token issued at sign-in.

:::note Administrator holds role:Admin but still gets 403 on everything On a fresh install this means the startup role reconcile has not run, so role:Admin exists in Keycloak as an empty shell with no permissions inside it. Confirm the backend runs with AUTHZ_RECONCILE_ON_STARTUP=true, restart it, and check that role:Admin lists perm:* roles as composites in Keycloak. :::

Keycloak is inaccessible​

If the login page itself fails to load, or the browser shows a connection error when trying to reach Keycloak, the Keycloak Docker container may have stopped.

Fix:

  1. SSH into the server and run docker ps to see which containers are running.
  2. If the Keycloak container is not listed or shows status Exited, restart it: docker compose up -d keycloak.
  3. Check Keycloak container logs for startup errors: docker compose -f infra/docker-compose.yml logs keycloak (the Keycloak service uses Compose's default name, not a custom one).
  4. Wait for Keycloak to fully start (it can take 30-60 seconds) before attempting to log in again.

Redirect loop​

If the browser keeps bouncing between the OpSee app and the Keycloak login page without ever settling, there is likely a misconfiguration in the OAuth2 Proxy or the Keycloak client settings.

Possible causes:

  • The redirect URI registered in the Keycloak client does not match the actual application URL.
  • The OAuth2 Proxy cookie secret has changed or is missing.
  • The SERVER_DOMAIN environment variable does not match the domain the browser is using.

Fix: Contact your infrastructure administrator. This type of issue requires access to the Docker Compose configuration and the Keycloak admin console to correct the client settings.