Update README.md
This commit is contained in:
159
README.md
159
README.md
@ -1,123 +1,80 @@
|
||||
# HSP Guard
|
||||
# 🛡️ HSP Guard
|
||||
|
||||
**HSP Guard** is an internal security service for your home lab, designed to manage user access to various home services and tools. It dynamically controls permissions and prevents unauthorized or unexpected users from accessing sensitive services.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 📌 Overview
|
||||
## ✨ Features
|
||||
|
||||
HSP Guard authorizes user requests and provides an efficient way to:
|
||||
|
||||
- Manage permissions for individual services/tools
|
||||
- Define roles for easier access control
|
||||
- Validate and authorize users via JWT tokens
|
||||
- Securely integrate with new services during installation
|
||||
- **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)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Concepts
|
||||
## 🚀 Getting Started
|
||||
|
||||
### 🔐 Permission
|
||||
### 1. **Run HSP Guard**
|
||||
|
||||
Permissions define access to specific features or tools.
|
||||
By default, HSP Guard includes predefined administrative permissions that allow an admin to log in and configure the system.
|
||||
You can run HSP Guard via Docker, Docker Compose, or natively (see below).
|
||||
|
||||
Once logged in, the admin can:
|
||||
### 2. **Register Your First App**
|
||||
|
||||
- Manually create new permissions for specific applications
|
||||
- Allow new applications to register their own permissions
|
||||
- Assign permissions to users, granting them access to corresponding tools
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
### 🧩 Role
|
||||
## 🏗️ Concepts
|
||||
|
||||
A **Role** is a named collection of permissions (e.g., `GUEST`, `FRIEND`, `FAMILY_MEMBER`) created by the admin.
|
||||
Roles simplify user management by allowing bulk assignment of permissions. Instead of assigning multiple permissions individually, a role bundles them under one label.
|
||||
### 🔑 **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.
|
||||
|
||||
---
|
||||
|
||||
### 👥 Group *(Coming Soon)*
|
||||
## 🔗 OIDC/OAuth Integration
|
||||
|
||||
This feature is planned for future releases. Groups will help organize users or services into logical clusters for simplified access control.
|
||||
**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
|
||||
|
||||
## 📡 API
|
||||
|
||||
### ✅ User Authorization
|
||||
|
||||
To verify whether a request is made by a valid and authorized user, applications can require a **JWT token** as part of the request.
|
||||
This token is sent to HSP Guard, which:
|
||||
|
||||
- Validates the token
|
||||
- Returns user details (e.g., ID, name, email) for logging, auditing, or request tracing
|
||||
|
||||
---
|
||||
|
||||
### 🔑 Permission Checking
|
||||
|
||||
Applications can also verify whether a user holds specific permissions before granting access to certain services or features.
|
||||
|
||||
To do this, an app sends:
|
||||
|
||||
- The user's JWT token
|
||||
- A list of required permissions
|
||||
|
||||
HSP Guard checks the user’s assigned permissions and responds with the authorization status.
|
||||
|
||||
> **Best Practice:** Applications should directly integrate with HSP Guard to enforce permission-based access control.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 User Authorization Flow
|
||||
|
||||
When a user tries to access a home lab service that requires authentication:
|
||||
|
||||
1. The application will **offer an authorization URL** to the user.
|
||||
2. The user follows the URL and is taken to the **HSP Guard login page**.
|
||||
3. The user selects or signs into an account they wish to use for that service.
|
||||
4. Once authenticated and authorized, the user is redirected to the **application-defined redirect URL**.
|
||||
5. The application can now:
|
||||
- Retrieve a **JWT token** from the redirect callback
|
||||
- **Optionally cache the session/token** to avoid prompting the user every time
|
||||
|
||||
This process is similar to how external identity providers like **Google Sign-In** or **GitHub OAuth** work — providing a seamless and secure authentication experience for the user.
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Integrating New Services & Tools
|
||||
|
||||
When a new service or tool is installed:
|
||||
|
||||
1. It provides a configuration file to HSP Guard
|
||||
2. Guard extracts and registers any defined permissions
|
||||
3. These permissions are **isolated** — even if a name overlaps with existing permissions, a prefix is added to avoid conflicts
|
||||
|
||||
---
|
||||
|
||||
## 👤 User Registration & Onboarding
|
||||
|
||||
New users (e.g., family, friends, guests) must complete a registration process to access your home lab.
|
||||
|
||||
They can:
|
||||
|
||||
- Visit a user-friendly registration webpage
|
||||
- Fill out a form with basic information (name, email, password, etc.)
|
||||
|
||||
Once registered, the admin can assign roles or individual permissions as needed.
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Roadmap
|
||||
|
||||
- [ ] Group Management
|
||||
- [ ] Web UI Enhancements
|
||||
- [ ] Audit Logging
|
||||
- [ ] Permission Expiry & Time-Based Access
|
||||
|
||||
---
|
||||
|
||||
## 📬 Feedback & Contribution
|
||||
|
||||
Feel free to open an issue or pull request if you’d like to contribute or report bugs. HSP Guard is a personal home lab project, but feedback is always welcome!
|
||||
#### **Example Token Claims**
|
||||
```json
|
||||
{
|
||||
"sub": "123456",
|
||||
"name": "Alex Example",
|
||||
"email": "alex@example.com",
|
||||
"roles": ["GUEST"],
|
||||
"permissions": ["dashboard.view", "music.play"]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user