From 6570c7aabc9cea28a4d1b32572c0349e473a4eab Mon Sep 17 00:00:00 2001 From: Astra Logical Date: Sat, 25 Jul 2026 19:16:35 -0400 Subject: [PATCH] AI pass at keycloak --- .../keycloak-account.md | 117 ++++++++++-------- 1 file changed, 62 insertions(+), 55 deletions(-) diff --git a/user-facing/communication-and-security/keycloak-account.md b/user-facing/communication-and-security/keycloak-account.md index 23ae5fc..e9fc242 100644 --- a/user-facing/communication-and-security/keycloak-account.md +++ b/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. - -## 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 +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. --- -*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!*