🛡️ HSP Guard

HSP Guard is a modern OpenID Connect (OIDC) identity provider and access management system for home labs. It provides secure authentication and granular authorization for all your self-hosted services, combining ease of use with enterprise-level control — without any vendor lock-in.

---

✨ Features

• OIDC Provider: Central login for your home lab apps
• Admin UI: Manage apps, users, roles, permissions, and sessions
• API Tokens: Issue access tokens with embedded roles and permissions
• Flexible Authorization: Support for roles, permissions, and groups (future)
• App Registration: Register OAuth/OIDC clients with custom permissions
• Automatic Permission Sync: Optionally fetch app permissions from /.well-known/guard-configuration
• User & Admin Sessions: See and revoke active user/app sessions
• Pluggable: Easily integrate new apps and services
• Audit Logging: Track actions for security and troubleshooting (planned)

---

🚀 Getting Started

1. Run HSP Guard

You can run HSP Guard via Docker, Docker Compose, or natively (see below).

2. Register Your First App

1. Login as admin
2. Go to Apps → Register New App
3. Enter:
   • Name of your app
   • Redirect URIs (for OIDC/OAuth callbacks)
   • (Optional) Permissions (manual or auto-discovered from the app)
4. Save to receive a client_id and client_secret
5. Configure your app to use these for OIDC login

3. Assign Permissions & Roles

• Assign default roles to new users automatically (configurable)
• Create custom roles to bundle permissions (e.g., FAMILY_MEMBER)
• Assign users to roles and/or groups for flexible access control

---

🏗️ Concepts

🔑 Permissions

Fine-grained controls for app features (e.g., music.play, dashboard.edit).
Can be manually defined or auto-discovered from an app’s .well-known/guard-configuration endpoint.

🧩 Roles

Named bundles of permissions (e.g., GUEST, FAMILY_MEMBER, ADMIN).
Assign to users/groups for easier management.

👥 Groups

(Planned) Logical user collections (e.g., “Family”, “Guests”, “Admins”) for batch management of roles/permissions.

👤 Users

Each user has a unique profile, roles, and group memberships.

---

🔗 OIDC/OAuth Integration

HSP Guard is a standard-compliant OIDC Provider. Any app supporting OIDC/OAuth can integrate.

• Register app in admin panel to get client_id & client_secret
• Configure your app’s OIDC integration (see your app’s docs)
• Token claims include permissions and roles for easy authorization

Example Token Claims

{
  "sub": "123456",
  "name": "Alex Example",
  "email": "alex@example.com",
  "roles": ["GUEST"],
  "permissions": ["dashboard.view", "music.play"]
}