81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# 🛡️ 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**
|
||
```json
|
||
{
|
||
"sub": "123456",
|
||
"name": "Alex Example",
|
||
"email": "alex@example.com",
|
||
"roles": ["GUEST"],
|
||
"permissions": ["dashboard.view", "music.play"]
|
||
}
|