Authentication

Given that the majority of users will integrate the workspace with an external authentication provider (or deploy on a local machine), the default deployment is configured to not require authentication.

The following sections will help you set up our opt-in authentication mechanism.

⚠️ WARNING

Remember to run Sign out of Kloud Workspace from the Command Palette when you are done working, as your login session won't expire automatically.

Password Authentication

Passed authentication can be easily configured by setting an environment variable when deploying the workspace. Setting your password is as simple as defining an env variable:

• WS_AUTH_PASSWORD: Plaintext password for web login.
• WS_AUTH_PASSWORD_HASHED: Argon2 hash used for web login.

Automatic Cleanup

Authentication related environment variables are automatically removed once the workspace finishes starting up.

This means they will not be visible in your terminal sessions, child processes, or any application running inside the workspace.

docker run \
  -e WS_AUTH_PASSWORD=super_duper_secret \
  ghcr.io/kloudkit/workspace:v0.5.2

Creating a Hashed Password

To generate a hashed password, use the ws-cli tool (replacing "super_duper_secret" with your desired password):

$ echo -n super_duper_secret | ws secrets generate login
$argon2id$v=19$m=4096,t=3,p=1$z4DjJlJgI6S7fAdQC35ZQw$Rpu8CLMWedxJaH0eiFCetyoRbg+S8ow/RRyVCZzM6QE

💡 TIP

You can generate the password hash from within a running workspace for subsequent executions. Then restart the instance and set the value for WS_AUTH_PASSWORD_HASHED:

echo -n "your_password" | ws secrets generate --workspace --raw

Then deploy the workspace:

docker run \
  -e WS_AUTH_PASSWORD_HASHED="$argon2id$v=19$m=4096,t=3,p=1$z4DjJlJgI6S7fAdQC35ZQw$Rpu8CLMWedxJaH0eiFCetyoRbg+S8ow/RRyVCZzM6QE" \
  ghcr.io/kloudkit/workspace:v0.5.2

File-Based Passwords

Instead of passing passwords as environment variables, you can mount them as files (useful with Docker secrets or Kubernetes Secret projections). Point the variable at the file with the file: prefix, or mount the file at the convention path and leave the variable unset.

docker run \
  -e WS_AUTH_PASSWORD_HASHED=file:/run/secrets/workspace/auth/password_hashed \
  -v ./password_hashed.txt:/run/secrets/workspace/auth/password_hashed:ro \
  ghcr.io/kloudkit/workspace:v0.5.2

See Resolving Secret Values for the full resolution chain and Kubernetes example.

Rate Limiting

The workspace has a built-in throttling mechanism to rate-limit password authentication attempts to two per minute and an additional twelve per hour.

OIDC Authentication (since v0.4.0)

To sign in with your identity provider (Keycloak, Entra ID, Authentik, or any OpenID Connect issuer), set WS_AUTH_MODE=oidc. An authenticating proxy then listens on port 38080 and checks every request, forwarded ports included, before it reaches the editor, which binds to loopback only. Publish 38080 instead of 8080.

• WS_AUTH_MODE: Web authentication mode, either password or oidc.
• WS_AUTH_OIDC_ISSUER: OIDC issuer URL. Required when WS_AUTH_MODE=oidc.
• WS_AUTH_OIDC_CLIENT_ID: OIDC client ID. Required when WS_AUTH_MODE=oidc.
• WS_AUTH_OIDC_CLIENT_SECRET: OIDC client secret. Required when WS_AUTH_MODE=oidc.

⚠️ WARNING

Serve the workspace over HTTPS. The session cookie is marked Secure, so over plain HTTP the browser drops it and sign-in loops back to the identity provider.

docker run \
  -p 38080:38080 \
  -e WS_AUTH_MODE=oidc \
  -e WS_AUTH_OIDC_ISSUER=https://idp.example.com/realms/ws \
  -e WS_AUTH_OIDC_CLIENT_ID=workspace \
  -e WS_AUTH_OIDC_CLIENT_SECRET=file:/run/secrets/workspace/auth/oidc_client_secret \
  ghcr.io/kloudkit/workspace:v0.5.2

Registering the Workspace

Register the workspace with your identity provider as a confidential client:

• Redirect URI: https://<workspace-host>/oauth2/callback.
• PKCE: allow S256.
• Groups: when you restrict access by group, add a groups claim to the ID token.

The issuer URL must resolve to the same host from your browser and from inside the workspace container.

Restricting Access

By default, any user your identity provider signs in is allowed. Narrow that down by group or by email:

• WS_AUTH_OIDC_ALLOWED_GROUPS: Restrict OIDC login to members of these IdP groups.
• WS_AUTH_OIDC_ALLOWED_EMAILS: Restrict OIDC login to an explicit email allowlist.
• WS_AUTH_OIDC_FORBIDDEN_MESSAGE: Custom guidance shown on the OIDC not-authorized (403) page.

A denied user sees your message and a Sign in as a different user button, which ends their session at the identity provider (since v0.5.3).

Forwarded Ports

When subdomain access is configured, the session cookie is scoped to the parent of WS_SERVER_PROXY_DOMAIN, so one sign-in covers the editor and every forwarded port.

⚠️ WARNING

A templated domain widens that scope: {{port}}-ws.example.com shares the session with every site under example.com. Prefer a dedicated subdomain such as *.ws.example.com.

Sessions

A session lasts seven days. The cookie secret is generated once and stored in the workspace home, so sessions survive restarts; set it explicitly when you redeploy without that volume or run several replicas:

• WS_AUTH_OIDC_COOKIE_SECRET: Secret that signs and encrypts the oauth2-proxy session cookie.

Sessions are not re-checked with the identity provider by default, so a user you disable there keeps access until the session expires. To re-check them periodically (since v0.5.3):

• WS_AUTH_OIDC_SESSION_REFRESH: How often a signed-in session is re-checked with the IdP.

💡 TIP

Add offline_access to WS_AUTH_OIDC_SCOPES so idle users refresh silently instead of being asked to sign in again. Keycloak, Entra ID and Authentik support it; Google does not.

⚠️ WARNING

If the identity provider refuses offline_access for a user, sign-in fails. In Keycloak, users need the offline_access role, which the default roles include.

Signing Out

The Sign out of Kloud Workspace command is only shown when a sign-out URL is known. It is derived from the active authentication mode and needs no configuration, but can be overridden:

• WS_EDITOR_LOGOUT_URL: Overrides the URL the in-IDE sign-out action navigates to.

With OIDC (since v0.5.3), signing out also ends your session at the identity provider when it advertises an end_session_endpoint, and you land on its signed-out page. Without one, only the workspace session ends, and the next visit may sign you straight back in.