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 click Sign out at the bottom of the File menu 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.1.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.1.2

File-Based Passwords

Instead of passing passwords as environment variables, you can mount them as files. This is useful with Docker secrets or mounted credential files.

• WS_AUTH_PASSWORD_FILE: Path to a file containing the plaintext password.
• WS_AUTH_PASSWORD_HASHED_FILE: Path to a file containing the Argon2 hashed password.

docker run \
  ghcr.io/kloudkit/workspace:v0.1.2 \
  -v ./my_hashed_password.txt:/run/secrets/workspace/auth_password_hashed

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.