🛡️ 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"]
}

---

📡 App Permission Discovery

If your app supports permission discovery:

• Expose /.well-known/guard-configuration endpoint listing available permissions
• When registering in HSP Guard, auto-fetch and display for approval

Example guard-configuration JSON

{
  "permissions": [
    "dashboard.view",
    "dashboard.edit",
    "dashboard.admin"
  ]
}

---

🔄 User & Admin Sessions

• List all active sessions (browser, app, device, timestamp)
• Revoke sessions (logout) from user or admin panel

---

📦 Planned Features & Roadmap

• Group Management for batch assignments
• Audit Logging of all admin/user actions
• Permission Expiry (time-limited access)
• Advanced Web UI (dark mode, mobile)
• External Identity Providers (login with Google, GitHub, etc.)

---

🛠️ Development

• See CONTRIBUTING.md for how to contribute!
• Pull requests and issues are welcome.

---

📝 License

MIT — open source, for the home lab community.

---

💬 Feedback

Open an issue or join the discussion!

---