AI pass at keycloak

user-facing/communication-and-security/keycloak-account.md

@@ -1,59 +1,66 @@
-# Your Account (Keycloak) — Identity & Passkeys
+# Managing Your Account & Passkeys
 
-Your identity on The Nest is managed by [Keycloak](https://keycloak.org/), an open-source identity and access management platform. Keycloak handles authentication, passkeys, and group-based authorization for all services.
+Your account across **The Nest** is managed by **Keycloak**, our central identity and access platform. Keycloak acts as the digital keyring for all services, ensuring your login experience is seamless, consistent, and passwordless.
-
-## What Keycloak Does
-
-- **Authentication:** Verifies your identity using WebAuthn passkeys (passwordless).
-- **Authorization:** Determines which services you can access based on your Keycloak groups.
-- **Single Sign-On (SSO):** One login grants access to all connected services (Matrix, Forgejo, Nextcloud, etc.).
-
-## Managing Your Account
-
-### Viewing Enrolled Passkeys
-
-1. Visit [sso.mynest.love](https://sso.mynest.love).
-2. Click **Account** (after signing in).
-3. Under **Security Devices**, you'll see all enrolled passkeys.
-
-### Adding a New Passkey
-
-1. Go to **Security Devices → Add** on the Keycloak account page.
-2. Follow the prompts to register a new device (smartphone, security key, etc.).
-3. Give it a recognizable name (e.g., "iPhone 15" or "YubiKey").
-
-### Removing a Passkey
-
-You can remove a passkey from **Security Devices**, but you must have at least one remaining. If you're down to your last passkey, Keycloak will prevent removal and prompt you to add another first.
-
-## Group-Based Access
-
-Your access to services is controlled by Keycloak groups. See [Requesting Service Access](../access-requests.md) for details on how to request new groups.
-
-Common groups include:
-
-| Group | Services Unlocked |
-|-------|-------------------|
-| `media-users` | Jellyfin, Sonarr, Radarr, Bazarr |
-| `music-users` | DroppedNeedle, slskd |
-| `books-users` | Calibre-Web, Shelfmark, Audiobookshelf |
-| `storage-users` | Nextcloud |
-| `ttrpg-users` | Foundry VTT |
-
-## Account Recovery
-
-If you lose access to all enrolled passkeys:
-
-1. Contact an admin via Matrix (`@nest:starling.mynest.love`).
-2. Verify your identity using your registered email address.
-3. The admin will reset your account, allowing you to re-enroll passkeys.
-
-## Related Services
-
-- [Matrix](../communication-and-security/matrix.md) — Uses Keycloak for SSO login
-- [Vaultwarden](../communication-and-security/vaultwarden.md) — Can store passkey credentials securely
-- [Forgejo](../productivity-and-creation/forgejo.md) — Uses Keycloak for authentication
 
 ---
 
-*TODO: Add screenshot of Keycloak account page showing security devices.*
+## What Keycloak Does
+
+Keycloak works behind the scenes to handle three core functions:
+
+* **Single Sign-On (SSO):** Log in once to gain access to all connected Nest applications (such as Matrix, Forgejo, or Vaultwarden).
+* **Passwordless Authentication:** Securely verifies your identity using WebAuthn passkeys instead of traditional passwords.
+* **Group Access Control:** Grants or restricts access to specific services based on your account's group memberships.
+
+---
+
+## Managing Your Passkeys
+
+You have full control over your authentication devices! You can view, add, or remove passkeys at any time directly from your account dashboard.
+
+### Viewing Your Enrolled Passkeys
+1. Visit [sso.mynest.love](https://sso.mynest.love) and sign in.
+2. Click on **Account** (or navigate to **Security Devices**).
+3. Here, you will see a list of all devices and passkeys currently linked to your account.
+
+### Adding a New Passkey
+1. From your Keycloak account page, navigate to **Security Devices** and click **Add**.
+2. Follow your browser or device prompts to register your new passkey (e.g., a smartphone, security key, or browser password manager).
+3. Give your passkey a recognizable name (such as *"Work Laptop"* or *"Personal iPhone"*) to keep track of your devices easily.
+
+### Removing a Passkey
+* To remove an old device, locate it under **Security Devices** and select **Delete**.
+* **Safety Feature:** Keycloak prevents you from deleting your final remaining passkey to ensure you don't lock yourself out. You must enroll a replacement passkey before removing the last one.
+
+---
+
+## Group-Based Permissions
+
+Your access to different applications across The Nest is managed through **Keycloak Groups**. In most cases, group names match the service they unlock (for example, belonging to the `foundry-vtt` group gives you access to Foundry VTT).
+
+To request access to additional services, please see the [Requesting Service Access](../access-requests.md) guide.
+
+---
+
+## Account Recovery
+
+If you lose access to all of your enrolled devices or passkeys:
+
+1. Reach out to an administrator on Matrix at `@nest:starling.mynest.love`.
+2. Verify your identity using the email address linked to your account.
+3. An administrator will send you a secure recovery link to reset your credentials and register a new passkey.
+
+---
+
+## Related Services
+
+Here are a few core platforms that integrate directly with Keycloak:
+
+* **[Matrix](../communication-and-security/matrix.md):** Unified chat and voice login via SSO.
+* **[Vaultwarden](../communication-and-security/vaultwarden.md):** Can store and manage passkeys securely across devices.
+* **[Forgejo](../productivity-and-creation/forgejo.md):** Seamless identity management for code repositories.
+
+---
+
+> [!NOTE]
+> *Screenshots of the Keycloak Security Devices page will be added in a future update!*