====== 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.

<panel type="default" title="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.
</panel>

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.

  - Log into kanidm (idm.waffle.tech)
  - Go to the Security tab
  - Click "Unlock Security Settings" and enter your password again
  - 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.

<panel type="default" title="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.
</panel>

  - SSH to login.waffle.tech with the username and Unix password you just set up.
  - Run ''kanidm login -D <your username>'' and enter your password.
  - 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.
  - Run ''kanidm person ssh add-publickey <your username> '<reference name for SSH key>' '<public key string>'''
  - You should now be able to SSH to login.waffle.tech via public key authentication.