Getting Started Guide

Welcome to waffle.tech! You're one of us now.

Setting your password

You should have received a password reset link from an administrator. If you haven't or you lost it or something, contact help@svc.waffle.tech to request a new one.

When you follow the link, you'll be prompted to set a password. This will become the primary password for your account. After setting a password, you'll be sent back to the login page to log in properly for the first time.

KanIDM

Waffle.tech uses an identity management (IDM) system to handle user accounts and authentication centrally. Specifically, we use KanIDM, an opinionated IDM written in Rust. Unlike more traditional IDMs like Microsoft Active Directory and Red Hat IDM that are built around LDAP and Kerberos, KanIDM is built for OAuth2/OIDC first. The kanidm-unixd daemon runs on our Linux machines to allow login via KanIDM (kanidm-unixd is a backend for PAM and NSS).

KanIDM has a very basic web interface where you can manage your authentication options, but it also has a command-line client with a lot more features. We'll use that in the next section.

Once you've logged in, you probably want to set a Unix password. For several reasons, the password for login to POSIX machines (e.g. sshing to login.waffle.tech) is managed separately from your main account password. You can set it to the same thing if you want, although there's a mild security advantage to using a different password for POSIX login.

  1. Log into kanidm (idm.waffle.tech)
  2. Go to the Security tab
  3. Click “Unlock Security Settings” and enter your password again
  4. Click “Update your Unix password”

If you want, you can also click on “Password and Authentication Settings” to set up a webauthn token or TOTP 2FA. In the future, 2FA or webauthn may be required, but for now we are living dangerously.

SSH key setup

Now, let's set up convenient SSH access.

KanIDM is Paranoid

First, a helpful tip about the kanidm client: just like the web interface, it usually doesn't let you change anything security sensitive without a fresh password challenge (to make sure someone didn't steal your long-lived session tokens or something). If you get an error message that you need to reauthenticate, run kanidm reauth and enter your password. This is the same idea as the “Unlock Security Settings” in the web interface, but on the CLI, so it's more annoying.

  1. SSH to login.waffle.tech with the username and Unix password you just set up.
  2. Run kanidm login -D <your username> and enter your password.
  3. Find the SSH public key you'd like to use for SSH access, e.g. the contents of the id_rsa.pub file generated by ssh-keygen. You'll also want to make up a reference name for this SSH key, so that you know which one it is if you put multiple SSH public keys in kanidm.
  4. Run kanidm person ssh add-publickey <your username> '<reference name for SSH key>' '<public key string>'
  5. You should now be able to SSH to login.waffle.tech via public key authentication.