140 lines
4.0 KiB
Markdown
140 lines
4.0 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"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📡 **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**
|
||
```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](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](https://github.com/yourusername/hsp-guard/issues) or join the discussion!
|
||
|
||
---
|